docs: some more guides and doc formatting (#564)

website/docs/clients/guides/copy-index-to-another-application.md

@@ -0,0 +1,9 @@
+---
+title: Copy or move an index
+---
+
+:::caution
+
+WIP
+
+:::

website/docs/clients/guides/copy-or-move-index.mdx

@@ -0,0 +1,114 @@
+---
+title: Copy or move an index
+---
+
+:::caution
+
+This method is made to be used within **the same Algolia application**, for cross application operations, [read our dedicated guide](/docs/clients/guides/copy-index-to-another-application).
+
+:::
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Copy an index
+
+When you copy an index, it doesn’t copy the associated analytics data. The new index starts fresh. Be careful when using the `operationIndex` method with the `copy` parameter to overwrite an existing index, as it associates the existing analytics data of the overwritten index with the new one.
+
+<Tabs
+  groupId="language"
+  defaultValue="javascript"
+  values={[
+    { label: 'JavaScript', value: 'javascript', }
+  ]
+}>
+<TabItem value="javascript">
+
+```js
+import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
+
+const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
+
+const { taskID } = await client.operationIndex({
+  indexName: '<SOURCE_INDEX_NAME>',
+  operationIndexParams: {
+    destination: '<DESTINATION_INDEX_NAME>',
+    operation: 'copy',
+  },
+});
+
+// Poll the task status until it's done
+await client.waitForTask({ indexName: '<DESTINATION_INDEX_NAME>', taskID });
+```
+
+</TabItem>
+</Tabs>
+
+## Rename/move an index
+
+Changing the name of an index doesn’t change the name of the index’s analytics. The new name references new analytics; the old and new analytics aren’t merged. If you want to preserve an index’s analytics history, you need to keep using the old name.
+
+<Tabs
+  groupId="language"
+  defaultValue="javascript"
+  values={[
+    { label: 'JavaScript', value: 'javascript', }
+  ]
+}>
+<TabItem value="javascript">
+
+```js
+import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
+
+const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
+
+const { taskID } = await client.operationIndex({
+  indexName: '<SOURCE_INDEX_NAME>',
+  operationIndexParams: {
+    destination: '<DESTINATION_INDEX_NAME>',
+    operation: 'move',
+  },
+});
+
+// Poll the task status until it's done
+await client.waitForTask({ indexName: '<DESTINATION_INDEX_NAME>', taskID });
+```
+
+</TabItem>
+</Tabs>
+
+## Scope your operation
+
+When the scope is absent from the request, the index will be fully copied, but you can also decide to specify the scope of what you'd like to copy.
+
+The available scopes are: `rules`, `settings`, `synonyms`. You can provide one or many.
+
+<Tabs
+  groupId="language"
+  defaultValue="javascript"
+  values={[
+    { label: 'JavaScript', value: 'javascript', }
+  ]
+}>
+<TabItem value="javascript">
+
+```js
+import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
+
+const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
+
+const { taskID } = await client.operationIndex({
+  indexName: '<SOURCE_INDEX_NAME>',
+  operationIndexParams: {
+    destination: '<DESTINATION_INDEX_NAME>',
+    operation: 'move',
+    scope: ['rules'],
+  },
+});
+
+// Poll the task status until it's done
+await client.waitForTask({ indexName: '<DESTINATION_INDEX_NAME>', taskID });
+```
+
+</TabItem>
+</Tabs>

website/docs/clients/guides/customized-client-usage.mdx

@@ -0,0 +1,136 @@
+---
+title: Customized client usage
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+You might want to customize how the API client works, by providing additional information to your request, adding user-agents or use your own HTTP requester.
+
+## Send additional information in your request with `requestOptions`
+
+The `requestOptions` parameter allows you to merge additional information with the client transporter, such as `headers` or `query parameters`.
+
+**Note: `requestOptions` overrides the default parameters that were previously set in the method and client.**
+
+<Tabs
+  groupId="language"
+  defaultValue="javascript"
+  values={[
+    { label: 'JavaScript', value: 'javascript', }
+  ]
+}>
+<TabItem value="javascript">
+
+```js
+await client.search(
+  {
+    requests: [
+      {
+        indexName: '<YOUR_INDEX_NAME>',
+        query: '<YOUR_QUERY>',
+        hitsPerPage: 50,
+      },
+    ],
+  },
+  {
+    // This header is added to the request
+    headers: {
+      'additional-header': 'hello',
+    },
+    // As we re-define `hitsPerPage`, it will override the value defined in the method's parameters.
+    queryParameters: {
+      hitsPerPage: 100,
+    },
+  }
+);
+```
+
+</TabItem>
+</Tabs>
+
+## Provide your own user-agent
+
+The API clients offers a method for you to append data to the current user-agent.
+
+<Tabs
+  groupId="language"
+  defaultValue="javascript"
+  values={[
+    { label: 'JavaScript', value: 'javascript', },
+    { label: 'Java', value: 'java', }
+  ]
+}>
+<TabItem value="javascript">
+
+> In the JavaScript client, user-agent are sent in the header via the `x-algolia-agent` property.
+
+```js
+import { searchClient } from '@experimental-api-clients-automation/client-search';
+
+const client = searchClient('<YOUR_APP_ID>', '<YOUR_API_KEY>');
+
+// This will append `my user agent (optional version)` to the current value of `x-algolia-agent` for every requests
+client.addAlgoliaAgent('my user agent', 'optional version');
+```
+
+</TabItem>
+
+<TabItem value="java">
+
+```java
+import com.algolia.utils.AlgoliaAgent;
+import com.algolia.api.SearchClient;
+
+// This will append `my user agent (optional version)` to the current value of `x-algolia-agent` for every requests
+SearchClient client = new SearchClient("<YOUR_APP_ID>", "<YOUR_API_KEY>",
+  new AlgoliaAgent.Segment[] {
+    new AlgoliaAgent.Segment("my user agent", "optional version")
+  }
+);
+```
+
+</TabItem>
+</Tabs>
+
+## Use your own HTTP requester
+
+You can override the default requester behavior by providing your requester logic at the initialization of the client.
+
+> Our clients provide an `echoRequester`, that will return the full payload of the request.
+
+<Tabs
+  groupId="language"
+  defaultValue="javascript"
+  values={[
+    { label: 'JavaScript', value: 'javascript', },
+    { label: 'Java', value: 'java', }
+  ]
+}>
+<TabItem value="javascript">
+
+```js
+import { searchClient } from '@experimental-api-clients-automation/client-search';
+import { echoRequester } from '@experimental-api-clients-automation/requester-node-http';
+
+const client = searchClient('<YOUR_APP_ID>', '<YOUR_API_KEY>', {
+  // The first parameter is the status to return
+  requester: echoRequester(200),
+});
+```
+
+</TabItem>
+
+<TabItem value="java">
+
+```java
+import com.algolia.utils.echo.EchoRequester;
+import com.algolia.api.SearchClient;
+
+SearchClient client = new SearchClient("<YOUR_APP_ID>", "<YOUR_API_KEY>",
+  new EchoRequester()
+);
+```
+
+</TabItem>
+</Tabs>

website/docs/clients/guides/send-data-to-algolia.mdx

@@ -31,8 +31,8 @@ To push data to Algolia, you need an Application ID and a valid API key with the
 // for the default version
 import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
 
-// you can also import the lite version, with search only versions
-// import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch-lite';
+// you can also import the lite version, with search only methods
+// import { algoliasearchLiteClient } from '@experimental-api-clients-automation/algoliasearch-lite';
 
 const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
 ```

website/docs/clients/guides/wait-for-a-task-to-finish.mdx

@@ -0,0 +1,50 @@
+---
+title: Wait for a task to finish
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> The `waitForTask` method is only available in the `search` client context.
+
+Some operations related to the Algolia index are not always instantaneous. Doing such operations with our API clients will provide a `taskID` in the response body, so you can later know what is the status of your operation.
+
+We provide a `waitForTask` helper method for you to easily wait for a specific task status.
+
+<Tabs
+  groupId="language"
+  defaultValue="javascript"
+  values={[
+    { label: 'JavaScript', value: 'javascript', }
+  ]
+}>
+<TabItem value="javascript">
+
+```js
+import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
+
+const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
+
+const { taskID } = await client.saveObject({
+  indexName: '<YOUR_INDEX_NAME>',
+  body: {
+    title: 'My Algolia Object',
+  },
+});
+
+// Poll the task status with defaults values
+await client.waitForTask({ indexName: '<YOUR_INDEX_NAME>', taskID });
+
+// Poll the task status with your options
+await client.waitForTask({
+  indexName: '<YOUR_INDEX_NAME>',
+  taskID,
+  // Number of maximum retries to do
+  maxRetries: 100,
+  // The time to wait between tries
+  timeout: (retryCount: number): number => Math.min(retryCount * 200, 5000),
+});
+```
+
+</TabItem>
+</Tabs>