[WebPubSub] Support invoke_event for webpubsub client

sdk/webpubsub/azure-messaging-webpubsubclient/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Release History
 
-## 1.1.1 (2024-XX-XX)
+## 1.2.0 (Unreleased)
+
+### Features Added
+
+- Add preview API `invoke_event`
 
 ### Other Changes
 

sdk/webpubsub/azure-messaging-webpubsubclient/README.md

@@ -77,6 +77,39 @@ client.send_to_group(group_name, "hello world", WebPubSubDataType.TEXT);
 # In the Console tab of your developer tools found in your browser, you should see the message printed there.
 ```
 
+### 5. Invoke upstream events (preview)
+
+`invoke_event` sends an `invoke` request to the service, awaits the correlated `invokeResponse`, and returns the payload.
+
+```python
+from azure.messaging.webpubsubclient import WebPubSubClient
+from azure.messaging.webpubsubclient.models import WebPubSubDataType
+
+client = WebPubSubClient("<client-access-url>")
+with client:
+    result = client.invoke_event("processOrder", {"orderId": 1}, WebPubSubDataType.JSON)
+    print(f"Invocation result: {result.data}")
+```
+
+You can pass a `timeout` (in seconds) to limit how long the client waits for the response. An `InvocationError` is raised if the timeout elapses.
+
+```python
+from azure.messaging.webpubsubclient import WebPubSubClient
+from azure.messaging.webpubsubclient.models import WebPubSubDataType, InvocationError
+
+client = WebPubSubClient("<client-access-url>")
+with client:
+    try:
+        result = client.invoke_event(
+            "processOrder", {"orderId": 1}, WebPubSubDataType.JSON, timeout=5.0,
+        )
+        print(f"Invocation result: {result.data}")
+    except InvocationError as e:
+        print(f"Invocation failed: {e}")
+```
+
+_Streaming and service-initiated invocations are not yet supported._
+
 ---
 ## Examples
 ### Add callbacks for connected, disconnected and stopped events