Update api reference and associated texts

Author: tomasMizera

src/.vitepress/sidebar/en.js

@@ -100,8 +100,8 @@ export default {
       collapsed: true,
       items: [
         { text: 'Custom Mobile App', link: '/dev/customapp/' },
-        { text: 'Python Client Module Integration', link: '/dev/integration/' },
-        { text: 'C++ Standalone Client Integration', link: '/dev/integration-cpp/' },
+        { text: 'Python API Client', link: '/dev/integration/' },
+        { text: 'C++ API Client', link: '/dev/integration-cpp/' },
         { text: 'PostgreSQL DB Sync', link: '/dev/dbsync/' },
         { text: 'Media Sync', link: '/dev/media-sync/' },
         { text: 'Work Packages', link: '/dev/work-packages/' },

src/dev/integration-cpp/index.md

@@ -1,14 +1,14 @@
-# C++ Standalone Client Integration
+# C++ API Client
 [[toc]]
 
 Do you want to integrate <MainPlatformNameLink />? <MainPlatformName /> is an open platform that aims to be developer friendly and it has been designed to allow easy integration with other software.
 
-## C++ client installation
-C++ client is completely without any dependencies. To install the C++ client, just download the binary for your platform from <GitHubRepo id="MerginMaps/cpp-api-client/releases"/> and use it from the command line.
+## Installation
+C++ API client is completely without any dependencies. To install the client, just download the binary for your platform from <GitHubRepo id="MerginMaps/cpp-api-client/releases"/> and use it from the command line.
 
-Go to <GitHubRepo id="MerginMaps/cpp-api-client" /> repository for more information on how to use it.
+The client uses Qt-based <GitHubRepo id="MerginMaps/mobile/tree/master/core" desc="Mergin Maps API core library" /> used by the <MainDomainNameLink desc="mobile app" /> to sync the projects in the mobile application. Go to <GitHubRepo id="MerginMaps/cpp-api-client" /> repository for more information on how to use it. 
 
-## Command line tool
+## Command line interface
 When the client is installed, it comes with `mergin` command line tool.
 
 ```bash 
@@ -28,7 +28,3 @@ Commands:
   sync           Pull&Push the changes
   remove         Remove project from server.
 ```
-
-## Mergin Maps API core library 
-
-C++ Client is based on the Qt-based <GitHubRepo id="MerginMaps/mobile/tree/master/core" desc="Mergin Maps API core library" /> used by the <MainDomainNameLink desc="Mergin Maps mobile app" /> to sync the projects in the mobile application.

src/dev/integration/index.md

@@ -1,19 +1,30 @@
-# Python Client Module Integration
+---
+outline: deep
+---
+
+# Python API Client
 [[toc]]
 
 Do you want to integrate <MainPlatformNameLink />? <MainPlatformName /> is an open platform that aims to be developer friendly and it has been designed to allow easy integration with other software.
 
-## Python client module installation
-The Python client module is the easiest way to programmatically use <MainPlatformNameLink />. You can use Python API or a command-line tool to easily work with <MainPlatformName /> projects, such as to get project status, push and pull changes, or to download, create and delete projects.
-
-The <GitHubRepo id="MerginMaps/python-api-client" /> repository contains the source code of the Python client module and more information on how to use it.
+## Installation
+The Python client module is the easiest way to programmatically use <MainPlatformNameLink />. You can use Python API or a command-line tool to easily work with your projects, such as to get project status, push and pull changes. You can also create user accounts and manage their roles.
 
 Python client is available in the PyPI repository and can be installed with `pip`:
 
 ```
 pip3 install mergin-client
 ```
 
+## Command line interface
+For those who prefer using terminal, there is `mergin` command line tool shipped with the Python client. With several built-in commands, it is possible to download <MainPlatformName /> projects, push/pull changes, create or delete projects and more.
+
+For example, to download a <MainPlatformName /> project to a local folder:
+```
+mergin download john/project1 ~/mergin/project1
+```
+For more details, visit <GitHubRepo id="MerginMaps/python-api-client" />.
+
 ## Python module 
 To use <MainPlatformNameLink /> from Python, just create `MerginClient` object and then use it. Here, for instance, to download a project:
 
@@ -30,132 +41,170 @@ import Mergin.mergin as mergin
 client = mergin.MerginClient(login='john', password='T0p_secret')
 ```
 
-## User and roles management in Python module
-You can create new users and manage their permissions using the following methods:
+## API reference - users
+
+You can create new users and manage their roles using the following methods.
+
+::: warning API availability
+The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher.
+:::
 
 ### Create a user
 
 ```python
 client.create_user(<email>, <password>, <workspace_id>, <workspace_role>, [username], [notify_user])
 ```
+
+The caller must be a workspace admin, owner or server administrator.
+
 Arguments:
 
 `email` (string): Must be a unique email.
 
 `password` (string): Must meet security requirements.
 
-`workspace_id` (int): The workspace ID where the user will be added.
+`workspace_id` (int)⭐️ : The workspace ID where the user will be added.
 
-`workspace_role`(string): The user’s role in the workspace. [See the roles options](../../manage/permissions.md).
+`workspace_role` (string)⭐️ : The user’s role in the workspace. [See the roles options](../../manage/permissions.md#workspace-member-roles-overview).
 
-`username` (string, optional): Custom username; if not provided, it will be automatically generated.
+`username` (string, optional): If not provided, it will be automatically generated from the email address.
 
-`notify_user` (Boolean, optional): Flag for email notifications (invitations, access requests etc.). Default is `False`.
+`notify_user` (Boolean, optional): If true, confirmation email and other email communication will be sent to the email address (invitations, access requests etc.). Default is `False`.
 
 Example:
 ```python
 client.create_user("jill@example.com", "T0p_secret", 1, "editor", notify_user=True)
 ```
 
-### Get a workspace member detail
+> ⭐️ `workspace_id` and `workspace_role` arguments are ignored on Community edition servers.
+
+---
+
+### Workspace members methods
+
+These methods are available for Cloud and Enterperise edition servers.
+
+::: warning API availability
+The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher.
+:::
+
+The caller of the following methods must be a workspace admin, owner or server administrator.
+
+#### List members
 
 ```python
-client.get_workspace_member(<workspace_id>, <user_id>)
+client.list_workspace_members(<workspace_id>)
 ```
 Arguments:
 
-`workspace_id` (int): The workspace ID used to retrieve the user's roles for the workspace and its projects.
-
-`user_id` (int): ID of the user.
+`workspace_id` (int): ID of the workspace.
 
-### Get a list of workspace members
+#### Get member detail
 
 ```python
-client.list_workspace_members(<workspace_id>)
+client.get_workspace_member(<workspace_id>, <user_id>)
 ```
 Arguments:
 
-`workspace_id` (int): The workspace ID to list the members.
+`workspace_id` (int): ID of the workspace.
+
+`user_id` (int): ID of the user.
 
-### Update workspace role
+#### Update member role
 
 ```python
 client.update_workspace_member(<workspace_id>, <user_id>, <workspace_role>, [reset_projects_roles])
 ```
 Arguments:
 
-`workspace_id` (int): Workspace ID where to update user's role.
+`workspace_id` (int): ID of the workspace.
 
-`user_id` (int): User to be updated.
+`user_id` (int): ID of the user.
 
-`workspace_role` (string): New role.
+`workspace_role` (string): New role. [See the roles options](../../manage/permissions.md#workspace-member-roles-overview).
 
-`reset_projects_roles` (Boolean, optional): Flag to remove all project specific roles.
+`reset_projects_roles` (Boolean, optional): If true, overriden project roles (explicitly shared projects access) will be reset. Default is `False`.
 
-### Remove a user from a workspace
+#### Remove member
 
 ```python
 client.remove_workspace_member(<workspace_id>, <user_id>)
 ```
 Arguments:
 
-`workspace_id` (int): Workspace ID from which to remove the user.
+`workspace_id` (int): ID of the workspace.
+
+`user_id` (int): ID of the user.
+
+> Note: the user account is not removed. This method only removes their access to the workspace.
+
+---
+
+### Project collaborators methods
+
+These methods are available for all server types.
+
+::: warning API availability
+The following methods are available for Python API Client versions `0.10.0` or higher, using server versions `2025.2.0` or higher.
+:::
 
-`user_id` (int): ID of the user to be removed.
+The caller of the following methods must be a workspace admin, owner, project owner or server administrator.
 
-### Get a list of project collaborators
+The following methods accept project ids (of type `uuid`). You can find project id via [projects_list](https://github.com/MerginMaps/python-api-client/blob/634237890afd9f28f03953e5a01376b56f5abf5c/mergin/client.py#L572) and [project_info](https://github.com/MerginMaps/python-api-client/blob/634237890afd9f28f03953e5a01376b56f5abf5c/mergin/client.py#L642) methods.
+
+#### List project collaborators
 
 ```python
 client.list_project_collaborators(<project_id>)
 ```
 Arguments:
 
-`project_id` (string): Project ID to list the users.
+`project_id` (string): ID of the project.
+
+#### Add project collaborator
 
-### Add a user to project
+Adds a user as project collaborator. This method is good for sharing projects with guests or upgrading roles of members for specific projects.
+On Cloud, the user must be a in the workspace where the project belongs.
 
 ```python
 client.add_project_collaborator(<project_id>, <user>, <project_role>)
 ```
 Arguments:
 
-`project_id` (string): Project ID to add the user.
+`project_id` (string): ID of the project.
 
-`user` (string): Email or username of the user to be added to the project.
+`user` (string): Email or username of the user to be added to the project. 
 
-`project_role`: (string): Role of the user in the project.
+`project_role`: (string): Role of the user in the project. [See the roles options](../../manage/permissions.md##project-permissions-overview)
 
-### Update project role
+#### Update project collaborator role
 
 ```python
 client.update_project_collaborator(<project_id>, <user_id>, <project_role>)
 ```
 Arguments:
 
-`project_id` (string): Project ID in which the role will be updated.
+`project_id` (string): ID of the project.
 
-`user_id` (int): ID of the user to update.
+`user_id` (int): ID of the user.
 
-`project_role`: (string): New role.
+`project_role`: (string): New role. [See the roles options](../../manage/permissions.md##project-permissions-overview)
 
-Note that the user must have a project role to update it. You can create one using the previous method.
+> Note: the user must be first added to the project (via [Add project collaborator](./index.md#add-project-collaborator)) before calling this method, even if he/she is already a workspace member or guest.
 
-### Update project role
+#### Remove project collaborator
 
 ```python
 client.remove_project_collaborator(<project_id>, <user_id>)
 ```
 Arguments:
 
-`project_id` (string): Project ID to remove the user.
+`project_id` (string): ID of the project.
 
-`user_id` (int): ID of the user to remove from the project.
+`user_id` (int): ID of the user.
 
-## Command line interface
-For those who prefer using terminal, there is `mergin` command line tool shipped with the Python client. With several built-in commands, it is possible to download <MainPlatformName /> projects, push/pull changes, create or delete projects and more.
+> Note: the user account is not removed, only the project access. 
 
-For example, to download a <MainPlatformName /> project to a local folder:
-```
-mergin download john/project1 ~/mergin/project1
-```
-For more details, visit <GitHubRepo id="MerginMaps/python-api-client" />.
+## Further details
+
+The <GitHubRepo id="MerginMaps/python-api-client" /> repository contains the source code and more information on how to use it.