Add v3.3 documents #939

.github/ISSUE_TEMPLATE/02_enhancement.md

@@ -15,7 +15,9 @@ assignees: ""
 - [ ] **slack_sdk.models** (UI component builders)
 - [ ] **slack_sdk.oauth** (OAuth Flow Utilities)
 - [ ] **slack_sdk.socket_mode** (Socket Mode client)
-- [ ] **slack_sdk.rtm.RTMClient** (RTM client)
+- [ ] **slack_sdk.audit_logs** (Audit Logs API client)
+- [ ] **slack_sdk.scim** (SCIM API client)
+- [ ] **slack_sdk.rtm** (RTM client)
 - [ ] **slack_sdk.signature** (Request Signature Verifier)
 
 ### Requirements

.github/pull_request_template.md

@@ -9,7 +9,9 @@
 - [ ] **slack_sdk.models** (UI component builders)
 - [ ] **slack_sdk.oauth** (OAuth Flow Utilities)
 - [ ] **slack_sdk.socket_mode** (Socket Mode client)
-- [ ] **slack_sdk.rtm.RTMClient** (RTM client)
+- [ ] **slack_sdk.audit_logs** (Audit Logs API client)
+- [ ] **slack_sdk.scim** (SCIM API client)
+- [ ] **slack_sdk.rtm** (RTM client)
 - [ ] **slack_sdk.signature** (Request Signature Verifier)
 - [ ] `/docs-src` (Documents, have you run `./docs.sh`?)
 - [ ] `/docs-src-v2` (Documents, have you run `./docs-v2.sh`?)

docs-src/audit-logs/index.rst

@@ -0,0 +1,51 @@
+==============================================
+Audit Logs API Client
+==============================================
+
+`Audit Logs API <https://api.slack.com/admins/audit-logs>`_ is a set of APIs for monitoring what’s happening in your `Enterprise Grid <https://api.slack.com/enterprise/grid>`_ organization.
+
+The Audit Logs API can be used by security information and event management (SIEM) tools to provide an analysis of how your Slack organization is being accessed. You can also use this API to write your own applications to see how members of your organization are using Slack.
+
+Follow the instructions in `the API document <https://api.slack.com/admins/audit-logs>`_ to get a valid token for using Audit Logs API. The Slack app using the Audit Logs API needs to be installed in the Enterprise Grid Organization, not an individual workspace within the organization.
+
+AuditLogsClient
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An OAuth token with `the admin scope <https://api.slack.com/scopes/admin>`_ is required to access this API.
+
+You will likely use the ``/logs`` endpoint as it's the essential part of this API.
+
+To learn about the available parameters for this endpoint, check out `this guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. You can also learn more about the data structure of ``api_response.typed_body`` from `the class source code <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.
+
+.. code-block:: python
+
+    import os
+    from slack_sdk.audit_logs import AuditLogsClient
+
+    client = AuditLogsClient(token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"])
+
+    api_response = self.client.logs(action="user_login", limit=1)
+    api_response.typed_body  # slack_sdk.audit_logs.v1.LogsResponse
+
+If you would like to access ``/schemes`` or ``/actions``, you can use the following methods:
+
+.. code-block:: python
+
+    api_response = self.client.schemas()
+    api_response = self.client.actions()
+
+AsyncAuditLogsClient
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are keen to use asyncio for SCIM API calls, we offer AsyncSCIMClient for it. This client relies on aiohttp library.
+
+.. code-block:: python
+
+    from slack_sdk.audit_logs.async_client import AsyncAuditLogsClient
+    client = AsyncAuditLogsClient(token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"])
+
+    api_response = await self.client.logs(action="user_login", limit=1)
+    api_response.typed_body  # slack_sdk.audit_logs.v1.LogsResponse
+
+
+.. include:: ../metadata.rst

docs-src/index.rst

@@ -8,6 +8,8 @@
      webhook/index
      socket-mode/index
      oauth/index
+     audit-logs/index
+     scim/index
      real_time_messaging
      faq
      about
@@ -31,7 +33,11 @@ The Slack platform offers several APIs to build apps. Each Slack API delivers pa
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
 | OAuth                          | Setup the authentication flow using V2 OAuth for Slack apps.                                  | ``slack_sdk.oauth``                |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
-| RTM API                        | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | ``slack_sdk.rtm```                 |
+| Audit Logs API                 | Receive audit logs API data.                                                                  | ``slack_sdk.audit_logs``           |
++--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
+| SCIM API                       | Utilize the SCIM APIs for provisioning and managing user accounts and groups.                 | ``slack_sdk.scim``                 |
++--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
+| RTM API                        | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | ``slack_sdk.rtm.v2``               |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
 | Request Signature Verification | Verify incoming requests from the Slack API servers.                                          | ``slack_sdk.signature``            |
 +--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+

docs-src/real_time_messaging.rst

@@ -1,3 +1,4 @@
+
 .. _real-time-messaging:
 
 ==============================================
@@ -7,12 +8,9 @@ RTM Client
 Real Time Messaging (RTM)
 ---------------------------------------
 
-
 The `Real Time Messaging (RTM) API`_ is a WebSocket-based API that allows you to receive events from Slack in real time and send messages as users.
 
-If you prefer events to be pushed to your app, we recommend using the HTTP-based `Events API <https://api.slack.com/events-api>`_ instead. 
-The Events API contains some events that aren't supported in the RTM API (like `app_home_opened event <https://api.slack.com/events/app_home_opened>`_),
-and it supports most of the event types in the RTM API. If you'd like to use the Events API, you can use the `Python Slack Events Adaptor <https://github.com/slackapi/python-slack-events-api>`_.
+If you prefer events to be pushed to your app, we recommend using the HTTP-based `Events API <https://api.slack.com/events-api>`_ along with `Socket Mode <https://api.slack.com/socket-mode>`_ instead. The Events API contains some events that aren't supported in the RTM API (like `app_home_opened event <https://api.slack.com/events/app_home_opened>`_), and it supports most of the event types in the RTM API. If you'd like to use the Events API, you can use the `Python Slack Events Adaptor <https://github.com/slackapi/python-slack-events-api>`_.
 
 The RTMClient allows apps to communicate with the Slack Platform's RTM API.
 
@@ -30,6 +28,35 @@ Also, even if the Slack app configuration pages encourage you to upgrade to the
 
 **Connecting to the RTM API**
 
+Note that the import here is not ``from slack_sdk.rtm import RTMClient`` but ``from slack_sdk.rtm.v2 import RTMClient`` (``v2`` is added in the latter one). If you would like to use the legacy version of the client, go to the next section.
+
+.. code-block:: python
+
+    import os
+    from slack_sdk.rtm.v2 import RTMClient
+
+    rtm = RTMClient(token=os.environ["SLACK_BOT_TOKEN"])
+
+    @rtm.on("message")
+    def handle(client: RTMClient, event: dict):
+        if 'Hello' in event['text']:
+            channel_id = event['channel']
+            thread_ts = event['ts']
+            user = event['user'] # This is not username but user ID (the format is either U*** or W***)
+
+            client.web_client.chat_postMessage(
+                channel=channel_id,
+                text=f"Hi <@{user}>!",
+                thread_ts=thread_ts
+            )
+
+    rtm.start()
+
+
+**Connecting to the RTM API (v1 client)**
+
+Below is a code snippet that uses the legacy version of ``RTMClient``. For new app development, we **do not recommend** using it as it contains issues that have been resolved in v2. Please refer to the `list of these issues <https://github.com/slackapi/python-slack-sdk/issues?q=is%3Aissue+is%3Aclosed+milestone%3A3.3.0+label%3Artm-client>`_ for more details.
+
 .. code-block:: python
 
     import os
@@ -88,11 +115,9 @@ If you'd rather use ``rtm.start`` to establish the connection, which provides mo
     )
     rtm_client.start()
 
-Read the `rtm.connect docs <https://api.slack.com/methods/rtm.connect>`_ and the `rtm.start docs <https://api.slack.com/methods/rtm.start>`_ for more details.
-
+Read the `rtm.connect docs <https://api.slack.com/methods/rtm.connect>`_ and the `rtm.start docs <https://api.slack.com/methods/rtm.start>`_ for more details. Also, note that ``slack.rtm.v2.RTMClient`` does not support ``rtm.start``.
 
-RTM Events
--------------
+**RTM Events**
 
 .. code-block:: javascript
 

docs-src/scim/index.rst

@@ -0,0 +1,97 @@
+==============================================
+SCIM API Client
+==============================================
+
+`SCIM API <https://api.slack.com/scim>`_ is a set of APIs for provisioning and managing user accounts and groups. SCIM is used by Single Sign-On (SSO) services and identity providers to manage people across a variety of tools, including Slack.
+
+`SCIM (System for Cross-domain Identity Management) <http://www.simplecloud.info/>`_ is supported by a myriad of services. It behaves slightly differently from other Slack APIs.
+
+Refer to `the API document <https://api.slack.com/scim>`_ for more details.
+
+SCIMClient
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An OAuth token with `the admin scope <https://api.slack.com/scopes/admin>`_ is required to access the SCIM API.
+
+To fetch provisioned user data, you can use the ``search_users`` method in the client.
+
+.. code-block:: python
+
+    import os
+    from slack_sdk.scim import SCIMClient
+
+    client = SCIMClient(token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"])
+
+    response = client.search_users(
+        start_index=1,
+        count=100,
+        filter="""filter=userName Eq "Carly"""",
+    )
+    response.users  # List[User]
+
+Check out `the class source code <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/scim/v1/user.py>`_ to learn more about the structure of the ``user`` in ``response.users``.
+
+Similarly, the ``search_groups`` method is available and the shape of the ``Group`` object can be `found here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/scim/v1/group.py>`_.
+
+.. code-block:: python
+
+    response = client.search_groups(
+        start_index=1,
+        count=10,
+    )
+    response.groups  # List[Group]
+
+For creating, updating, and deleting users/groups:
+
+.. code-block:: python
+
+    # POST /Users
+    # Creates a user. Must include the user_name argument and at least one email address.
+    # You may provide an email address as the user_name value,
+    # but it will be automatically converted to a Slack-appropriate username.
+    user = User(
+        user_name="cal",
+        name=UserName(given_name="C", family_name="Henderson"),
+        emails=[UserEmail(value="your-unique-name@example.com")],
+    )
+    creation_result = self.client.create_user(user)
+
+    # PATCH /Users/{user_id}
+    # Updates an existing user resource, overwriting values for specified attributes.
+    patch_result = self.client.patch_user(
+        id=creation_result.user.id,
+        partial_user=User(user_name="chenderson"),
+    )
+
+    # PUT /Users/{user_id}
+    # Updates an existing user resource, overwriting all values for a user
+    # even if an attribute is empty or not provided.
+    user_to_update = patch_result.user
+    user_to_update.name = UserName(given_name="Cal", family_name="Henderson")
+    update_result = self.client.update_user(user=user_to_update)
+
+    # DELETE /Users/{user_id}
+    # Sets a Slack user to deactivated. The value of the {id}
+    # should be the user's corresponding Slack ID, beginning with either U or W.
+    delete_result = self.client.delete_user(user_to_update.id)
+
+AsyncSCIMClient
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Lastly, if you are keen to use asyncio for SCIM API calls, we offer ``AsyncSCIMClient`` for it. This client relies on aiohttp library.
+
+.. code-block:: python
+
+    import asyncio
+    import os
+    from slack_sdk.scim.async_client import AsyncSCIMClient
+
+    client = AsyncSCIMClient(token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"])
+
+    async def main():
+        response = await client.search_groups(start_index=1, count=2)
+        print(response.groups)
+
+    asyncio.run(main())
+
+.. include:: ../metadata.rst

docs/about.html

@@ -154,9 +154,18 @@
 <li class="toctree-l2"><a class="reference internal" href="oauth/index.html#token-lookup">Token Lookup</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="audit-logs/index.html">Audit Logs API Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#auditlogsclient">AuditLogsClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="audit-logs/index.html#asyncauditlogsclient">AsyncAuditLogsClient</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="scim/index.html">SCIM API Client</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="scim/index.html#scimclient">SCIMClient</a></li>
+<li class="toctree-l2"><a class="reference internal" href="scim/index.html#asyncscimclient">AsyncSCIMClient</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="real_time_messaging.html">RTM Client</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="real_time_messaging.html#real-time-messaging-rtm">Real Time Messaging (RTM)</a></li>
-<li class="toctree-l2"><a class="reference internal" href="real_time_messaging.html#rtm-events">RTM Events</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a><ul>