From 0829327ee646ef28752254dee5324b12b4202485 Mon Sep 17 00:00:00 2001 From: Zita Szupera Date: Fri, 12 Jul 2024 14:33:16 +0200 Subject: [PATCH] fix GDPR docs, remove code duplication --- .../docs/api/_common_/async-tasks.mdx | 49 +++++++++++++ .../api/_common_/deactivate-reactivate.mdx | 28 +++----- .../docs/api/_common_/delete-users.mdx | 71 +++++++++++++++++++ .../docs/api/basics/authentication.mdx | 64 +---------------- .../video/docusaurus/docs/api/gdpr/users.mdx | 56 +++------------ .../video/docusaurus/docs/api/misc/async.mdx | 32 ++------- 6 files changed, 148 insertions(+), 152 deletions(-) create mode 100644 docusaurus/video/docusaurus/docs/api/_common_/async-tasks.mdx create mode 100644 docusaurus/video/docusaurus/docs/api/_common_/delete-users.mdx diff --git a/docusaurus/video/docusaurus/docs/api/_common_/async-tasks.mdx b/docusaurus/video/docusaurus/docs/api/_common_/async-tasks.mdx new file mode 100644 index 00000000..65a97825 --- /dev/null +++ b/docusaurus/video/docusaurus/docs/api/_common_/async-tasks.mdx @@ -0,0 +1,49 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```js +// Example of monitoring the status of an async task +// The logic is same for all async tasks +const response = await client.(); + +// you need to poll this endpoint +const taskResponse = await client.getTaskStatus({id: response.task_id}) + +console.log(taskResponse.status === 'completed'); +``` + + + + +```py +# Example of monitoring the status of an async task +# The logic is same for all async tasks +response = client.() +task_id = response.data.task_id + +# get information about the task +task_status = client.get_task(task_id) + +# just an example, in reality it can take a few seconds for a task to be processed +if task_status.data.status == "completed": + print(task_status.data.result) +``` + + + + + +```bash +# When an operation is async, a task_id will be included in the API response +# That task_id can be used to monitor the status of the task +# When finished, task status will be completed +curl -X GET https://video.stream-io-api.com/api/v2/tasks/${TASK_ID}?api_key=${API_KEY} \ + -H "Authorization: ${TOKEN}" \ + -H "stream-auth-type: jwt" +``` + + + diff --git a/docusaurus/video/docusaurus/docs/api/_common_/deactivate-reactivate.mdx b/docusaurus/video/docusaurus/docs/api/_common_/deactivate-reactivate.mdx index 3341b805..599fe135 100644 --- a/docusaurus/video/docusaurus/docs/api/_common_/deactivate-reactivate.mdx +++ b/docusaurus/video/docusaurus/docs/api/_common_/deactivate-reactivate.mdx @@ -1,5 +1,6 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import AsyncTasks from '../_common_/async-tasks.mdx'; @@ -18,11 +19,6 @@ client.reactivateUsers({ const deactivateResponse = client.deactivateUsers({ user_ids: ['', ''...], }); - -// you need to poll this endpoint -const taskResponse = await client.getTaskStatus({id: deactivateResponse.task_id}) - -console.log(taskResponse.status === 'completed'); ``` @@ -37,14 +33,6 @@ client.reactivate_user(user_id=alice.id) # deactivates users in bulk, this is an async operation response = client.deactivate_users(user_ids=[alice.id, bob.id]) -task_id = response.data.task_id - -# get information about the task -task_status = client.get_task(task_id) - -# just an example, in reality it can take a few seconds for a task to be processed -if task_status.data.status == "completed": - print(task_status.data.result) ``` @@ -62,20 +50,20 @@ curl -X POST https://video.stream-io-api.com/api/v2/users/deactivate?api_key=${A }' # Reactivate users -curl -X POST https://video.stream-io-api.com/api/v2/users/deactivate?api_key=${API_KEY} \ +curl -X POST https://video.stream-io-api.com/api/v2/users/reactivate?api_key=${API_KEY} \ -H "Authorization: ${TOKEN}" \ -H "stream-auth-type: jwt" \ -H "Content-Type: application/json" \ -d '{ "user_ids": ["sara"] }' - -# Reactivate users in bulk can take some time, you can poll task status using the task id from the response -# When finished, task status will be completed -curl -X GET https://video.stream-io-api.com/api/v2/tasks/${TASK_ID}?api_key=${API_KEY} \ - -H "Authorization: ${TOKEN}" \ - -H "stream-auth-type: jwt" ``` + +Deactivating users in bulk can take some time, this is how you can check the progress: + + + +For more informiation, please refer to the [async operations guide](/api/misc/async) diff --git a/docusaurus/video/docusaurus/docs/api/_common_/delete-users.mdx b/docusaurus/video/docusaurus/docs/api/_common_/delete-users.mdx new file mode 100644 index 00000000..3aade0b4 --- /dev/null +++ b/docusaurus/video/docusaurus/docs/api/_common_/delete-users.mdx @@ -0,0 +1,71 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import AsyncTasks from '../_common_/async-tasks.mdx'; + +Deleting a user means: + +- the user can't connect to Stream API +- their data won't appear in user queries + +Delete has the following opitions: + +| Name | Type | Description | Optional | +| ---------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `user` | Enum (soft, pruning, hard) | - Soft: marks user as deleted and retains all user data.
- Pruning: marks user as deleted and nullifies user information.
- Hard: deletes user completely - this requires hard option for messages and conversation as well. | Yes | +| `conversations` | Enum (soft, hard) | - Soft: marks all conversation channels as deleted (same effect as Delete Channels with 'hard' option disabled).
- Hard: deletes channel and all its data completely including messages (same effect as Delete Channels with 'hard' option enabled). | Yes | +| `messages` | Enum (soft, pruning, hard) | - Soft: marks all user messages as deleted without removing any related message data.
- Pruning: marks all user messages as deleted, nullifies message information and removes some message data such as reactions and flags.
- Hard: deletes messages completely with all related information. | Yes | +| `new_channel_owner_id` | string | Channels owned by hard-deleted users will be transferred to this userID. If you doesn't provide a value, the channel owner will have a system generated ID like `delete-user-8219f6578a7395g` | Yes | +| `calls` | Enum (soft, hard) | - Soft: marks calls and related data as deleted.
- Hard: deletes calls and related data completely
Note that this applies only to 1:1 calls, not group calls | Yes | + + + + +```js +client.deleteUsers({ user_ids: [''] }); + +//restore +client.restoreUsers({ user_ids: [''] }); +``` + + + + + +```py +client.delete_users(user_ids=[""]) + +# restore +client.restore_users(user_ids=[""]) +``` + + + + +```bash +# Delete users +curl -X POST https://video.stream-io-api.com/api/v2/users/delete?api_key=${API_KEY} \ + -H "Authorization: ${TOKEN}" \ + -H "stream-auth-type: jwt" \ + -H "Content-Type: application/json" \ + -d '{ + "user_ids": ["sara"] + }' + +# Restore users +curl -X POST https://video.stream-io-api.com/api/v2/users/restore?api_key=${API_KEY} \ + -H "Authorization: ${TOKEN}" \ + -H "stream-auth-type: jwt" \ + -H "Content-Type: application/json" \ + -d '{ + "user_ids": ["sara"] + }' +``` + + + + +Deleting and restoring users in bulk can take some time, this is how you can check the progress: + + + +For more informiation, please refer to the [async operations guide](/api/misc/async) diff --git a/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx b/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx index 7dd84a9d..9835510b 100644 --- a/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx +++ b/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx @@ -8,6 +8,7 @@ title: Users & Tokens import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import DeactivateReactivate from '../_common_/deactivate-reactivate.mdx'; +import DeleteUsers from '../_common_/delete-users.mdx'; ## Creating users @@ -210,69 +211,10 @@ Deactivating a user means: - their data will be retained - a deactivated user can be reactivated -Deleting a user means: - -- the user can't connect to Stream API -- their data won't appear in user queries - -Delete has the following opitions: - -| Name | Type | Description | Optional | -| ---------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| `user` | Enum (soft, pruning, hard) | - Soft: marks user as deleted and retains all user data.
- Pruning: marks user as deleted and nullifies user information.
- Hard: deletes user completely - this requires hard option for messages and conversation as well. | Yes | -| `conversations` | Enum (soft, hard) | - Soft: marks all conversation channels as deleted (same effect as Delete Channels with 'hard' option disabled).
- Hard: deletes channel and all its data completely including messages (same effect as Delete Channels with 'hard' option enabled). | Yes | -| `messages` | Enum (soft, pruning, hard) | - Soft: marks all user messages as deleted without removing any related message data.
- Pruning: marks all user messages as deleted, nullifies message information and removes some message data such as reactions and flags.
- Hard: deletes messages completely with all related information. | Yes | -| `new_channel_owner_id` | string | Channels owned by hard-deleted users will be transferred to this userID. If you doesn't provide a value, the channel owner will have a system generated ID like `delete-user-8219f6578a7395g` | Yes | - - - - -```js -client.deleteUsers({ user_ids: [''] }); - -//restore -client.restoreUsers({ user_ids: [''] }); -``` - - - - - -```py -client.delete_users(user_ids=[""]) - -# restore -client.restore_users(user_ids=[""]) -``` - - - - -```bash -# Delete users -curl -X POST https://video.stream-io-api.com/api/v2/users/delete?api_key=${API_KEY} \ - -H "Authorization: ${TOKEN}" \ - -H "stream-auth-type: jwt" \ - -H "Content-Type: application/json" \ - -d '{ - "user_ids": ["sara"] - }' - -# Restore users -curl -X POST https://video.stream-io-api.com/api/v2/users/restore?api_key=${API_KEY} \ - -H "Authorization: ${TOKEN}" \ - -H "stream-auth-type: jwt" \ - -H "Content-Type: application/json" \ - -d '{ - "user_ids": ["sara"] - }' -``` - - - - + + ## User tokens Stream uses JWT (JSON Web Tokens) to authenticate chat users, enabling them to log in. Knowing whether a user is authorized to perform certain actions is managed separately via a role-based permissions system. Tokens need to be generated server-side. diff --git a/docusaurus/video/docusaurus/docs/api/gdpr/users.mdx b/docusaurus/video/docusaurus/docs/api/gdpr/users.mdx index 4d71f24b..a5dae02d 100644 --- a/docusaurus/video/docusaurus/docs/api/gdpr/users.mdx +++ b/docusaurus/video/docusaurus/docs/api/gdpr/users.mdx @@ -7,7 +7,8 @@ title: Users import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - +import DeleteUsers from '../_common_/delete-users.mdx'; +import AsyncTasks from '../_common_/async-tasks.mdx'; ## Users export @@ -17,35 +18,23 @@ _This endpoint requires a server-side authentication._ ::: -Stream allows you to export users with their data, including the calls they participated in. -The operation is performed asynchronously, so calling this endpoint will return a task ID that you can use to [monitor the execution of the export](../../misc/async). - -Once the task is completed, the result of the `GetTask` endpoint call will contain a URL to the file. +Stream allows you to export users with their data, including the calls they participated in. ```js -// export users -let resp = await client.exportUsers([userid1,userid2]); -// resp.task_id is the ID to be used for monitoring the task - -// when the export is done and the task is completed, an URL is returned to have access to the file -resp = await client.get_task(resp.task_id) -console.log(resp) -// output: -{ - "task_id": "123", - "status": "completed", - "result": { - "url": https://link/to/file.json' - } -} +await client.exportUsers({ user_ids: ['', ''] }); ``` +Exporting users can take some time, this is how you can check the progress: + + + +For more informiation, please refer to the [async operations guide](/api/misc/async) ## Users deletion @@ -58,29 +47,4 @@ _This endpoint requires a server-side authentication._ Stream allows you to delete users and optionally the calls they were part of. Note that this apply only to 1:1 calls, not group calls. -This operation is done asynchronously and you can use the returned `task_id` to monitor its progress. -See [how to monitor an async task](../../misc/async). - -Deleting a user accepts some parameters - -| param | type | description | required | -|----------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| -| user_ids | array | List of users who will be deleted | ✓ | -| user | enum (soft, pruning, hard) | **Soft:** marks user as deleted and retains all user data. (default) **Pruning:** marks user as deleted and nullifies user information. **Hard:** deletes user completely | | -| calls | enum (soft, hard) | **Soft:** marks calls and related data as deleted. **Hard:** deletes calls and related data completely | | - - - - - -```js -// hard delete users -let resp = await client.deleteUsers([userid1,userid2], { user: 'hard' }); -// resp.task_id is the ID to be used for monitoring the task - -// hard delete users and soft delete calls -resp = await client.deleteUsers([userid1,userid2], { user: 'hard', calls: 'soft' }); -// resp.task_id is the ID to be used for monitoring the task -``` - - + diff --git a/docusaurus/video/docusaurus/docs/api/misc/async.mdx b/docusaurus/video/docusaurus/docs/api/misc/async.mdx index 72212aff..1fd035e3 100644 --- a/docusaurus/video/docusaurus/docs/api/misc/async.mdx +++ b/docusaurus/video/docusaurus/docs/api/misc/async.mdx @@ -5,15 +5,16 @@ slug: /misc/async title: Asynchronous operations --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - +import AsyncTasks from '../_common_/async-tasks.mdx'; Certain operations, such as deleting a call or deleting a user, require additional time and processing power. As a result, these operations are executed asynchronously. +These tasks will return a `task_id` in the API response, you can use this id to monitor the task status. + ### Monitoring tasks You can monitor these tasks using the `GetTask` endpoint. Calling this endpoint will provide information such as: + - `status`: Current status of the task (see statuses below for more details) - `result`: Result of the task, depending on the nature of the task - `error`: If the task failed, this will contain information about the failure @@ -21,6 +22,7 @@ You can monitor these tasks using the `GetTask` endpoint. Calling this endpoint ### Task Statuses The task can have the following statuses: + - `pending`: Task is pending and not running yet - `running`: Task is running and not completed yet - `completed`: Task is completed and successfully executed @@ -29,25 +31,5 @@ The task can have the following statuses: ### Example Asynchronous operations will return an ID, which you can use to monitor the task. Here's an example: - - - -```js -// hard-delete a callm which will be executed asynchronously -let resp; -resp = await call.delete({hard: true}) - -// resp contains the task ID -resp = await client.get_task(resp.task_id) -console.log(resp) -// output: -{ - "task_id": "123", - "status": "running", - "error": null, // will be present only if there is an error - "result": {} // will be present only if the task returns a result -} -``` - - - + +