API docs updates (#278)

GetStream · Nov 2, 2023 · 5e9d712 · 5e9d712
2 parents 4f71173 + cf8c22a
commit 5e9d712
Show file tree

Hide file tree

Showing 21 changed files with 869 additions and 197 deletions.
diff --git a/docusaurus/video/docusaurus/docs/api/_common_/broadcast.mdx b/docusaurus/video/docusaurus/docs/api/_common_/broadcast.mdx
@@ -0,0 +1,33 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```js
+call.startHLSBroadcasting();
+
+// to end broadcasting
+call.stopHLSBroadcasting();
+```
+
+</TabItem>
+<TabItem value="py" label="Python">
+
+```py
+call.start_broadcasting()
+
+// to end broadcasting
+call.stop_broadcasting()
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -X POST "https://video.stream-io-api.com/video/call/default/${CALL_ID}/start_broadcasting?api_key=${API_KEY}" \
+-H "Authorization: ${JWT_TOKEN}"
+```
+
+</TabItem>
+</Tabs>
diff --git a/docusaurus/video/docusaurus/docs/api/_common_/go_live.mdx b/docusaurus/video/docusaurus/docs/api/_common_/go_live.mdx
@@ -6,6 +6,9 @@ import TabItem from '@theme/TabItem';
 
 ```js
 call.goLive();
+
+// optionally start HLS broadcast and/or recording
+call.goLive({ start_hls: true, start_recording: true });
 ```
 
 </TabItem>
@@ -16,4 +19,4 @@ call.go_live()
 ```
 
 </TabItem>
-</Tabs>
+</Tabs>
diff --git a/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx b/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx
@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 
 ## Creating users
 
-Stream Users require only an id to be created. Users can be created with role of user or admin. The role will be set to user if a value is not provided in the request. There are additional properties you can provide to further describe your users.
+Stream Users require only an ID to be created. Users can be created with the role of user or admin. The role will be set to user if a value is not provided in the request. There are additional properties you can provide to further describe your users.
 
 The `name` and `image` fields are special fields that are supported by client-side SDKs.
 
@@ -36,6 +36,18 @@ await client.upsertUsers({
 });
 ```
 
+</TabItem>
+<TabItem value="py" label="Python">
+
+```py
+users = {}
+user = UserRequest(
+id='user_id', role="user", custom={"color": "red"}, name="This is a test user",image= "link/to/profile/image",
+)
+users[user.id] = user
+client.upsert_users(users=users)
+```
+
 </TabItem>
 </Tabs>
 
@@ -44,7 +56,7 @@ await client.upsertUsers({
 There are two ways to update user objects:
 
 - Updating will replace the existing user object
-- Partial update will let you choose which fields you want to chage/unset
+- Partial update will let you choose which fields you want to change/unset
 
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
@@ -79,6 +91,38 @@ client.updateUsersPartial({
 });
 ```
 
+</TabItem>
+<TabItem value="py" label="Python">
+
+```py
+users = {}
+user = UserRequest(
+  id= 'userid',
+  role= 'user',
+  custom= {
+    "color": 'red',
+  },
+  name= 'This is a test user',
+  image= 'link/to/profile/image',
+)
+
+users[user.id] = user
+client.upsert_users(users=users)
+
+// or
+client.update_users_partial(
+  users= [
+    {
+      id: user.id,
+      set: {
+        color: 'blue',
+      },
+      unset: ['name'],
+    },
+  ],
+)
+```
+
 </TabItem>
 </Tabs>
 
@@ -88,7 +132,7 @@ Anonymous users are users that are not authenticated. It's common to use this fo
 
 ## Guest users
 
-Guest users are temporary user accounts. You can use it to temporarily give someone a name and image when joining a call. Guest users can aslso be created cliend-side.
+Guest users are temporary user accounts. You can use it to temporarily give someone a name and image when joining a call. Guest users can aslso be created client-side.
 
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
@@ -105,14 +149,32 @@ const guest: UserObjectRequest = {
 const guest = (await client.createGuest({ user: guest })).user;
 ```
 
+</TabItem>
+<TabItem value="py" label="Python">
+
+```py
+guest = UserRequest(
+  id = '<id>',
+  name= '<name>',
+  custom= {
+    "color": 'red',
+  },
+)
+
+guest = (client.video.create_guest(user=guest)).user
+```
+
 </TabItem>
 </Tabs>
 
 ## Deactivating and deleting users
 
 While it is usually safer for data retention to deactivate a user, some use cases require completely deleting a user and their data.
 
-Once a user has been deleted, it cannot be un-deleted and the user_id cannot be used again.
+Once a user has been deleted, it cannot be un-deleted, and the user_id cannot be used again.
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
 
 ```js
 client.deactivateUser({
@@ -122,14 +184,29 @@ client.deactivateUser({
 client.deleteUser({ userId: '<id>' });
 ```
 
+</TabItem>
+
+<TabItem value="py" label="Python">
+
+```py
+client.deactivate_user(
+  user_id= '<id>',
+)
+
+client.delete_user( user_id= '<id>' )
+```
+
+</TabItem>
+</Tabs>
+
 ## User tokens
 
-Stream uses JWT (JSON Web Tokens) to authenticate chat users, enabling them to login. 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.
+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.
 
 You can optionally provide
 
-- expiration time
-- issued at date which is necessary if you manually wan to revoke tokens
+- Expiration time. By default tokens don't have an expiration date.
+- Issued at date, which is necessary if you manually want to revoke tokens. By default, the issued at date is set to the current date.
 
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
@@ -179,12 +256,7 @@ const iat = Math.round(new Date().getTime() / 1000);
 
 const call_cids = ['default:call1', 'livestream:call2'];
 
-client.createToken(
-  (user_id = user_id),
-  (exp = exp),
-  (iat = iat),
-  (call_cids = call_cids),
-);
+client.createCallToken(userId, call_cids, exp, iat);
 ```
 
 </TabItem>
@@ -209,5 +281,5 @@ client.create_token(user_id=user_id, exp, iat, call_cids)
 
 ## Provisioning token in production
 
-Your authentication service is responsible for generating token for your users. It is highly recommended to always create tokens with an expiration.
-All SDK make it easy to automatically re-fetch tokens from your backend servers with token providers when they expire.
+Your authentication service is responsible for generating tokens for your users. It is highly recommended to always create tokens with an expiration.
+All SDKs make it easy to automatically re-fetch tokens from your backend servers with token providers when they expire.
diff --git a/docusaurus/video/docusaurus/docs/api/basics/calls.mdx b/docusaurus/video/docusaurus/docs/api/basics/calls.mdx
@@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem';
 
 You can create a call by providing the call type and an ID:
 
-- The [call type](call_types/builtin) controls which features are enabled, and sets up permissions.
+- The [call type](call_types/builtin) controls which features are enabled and sets up permissions.
 - Calls IDs can be reused, which means they can be joined multiple times, so it's possible to set up recurring calls.
 
 You can optionally restrict call access by providing a list of users.
@@ -43,13 +43,13 @@ call.create({
 
 ```py
 # create a call
-call.get_or_create_call(
+call.create(
     data=CallRequest(
         created_by_id='john'
     )
 )
 # create a call with more data
-call.get_or_create_call(
+call.create(
     data=CallRequest(
         created_by_id='john',
         members=[
@@ -109,7 +109,7 @@ call.update({ custom: { color: 'red' } });
 
 ```py
 # update call settings
-call.update_call(
+call.update(
     settings_override=CallSettingsRequest(
         audio=AudioSettingsRequest(
             mic_default_on=True,
@@ -118,7 +118,7 @@ call.update_call(
 )
 
 # update call with custom data
-call.update_call(
+call.update(
     custom={'color': 'red'}
 )
 ```
@@ -145,7 +145,7 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}?api_k
 
 ## Manage call members
 
-Call members can be added and removed as necessary. Their role's can also be changed.
+Call members can be added and removed as necessary. Their roles can also be changed.
 
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
@@ -168,7 +168,7 @@ call.updateCallMembers({
 ```py
 # update or add call members
 
-call.update_call(
+call.update_members(
     members=[
         MemberRequest(user_id: 'sara'),
         MemberRequest(user_id: 'jack', role: 'admin')
@@ -177,7 +177,7 @@ call.update_call(
 
 # remove call members
 # Assuming the updated call members are 'sara' and 'jack'
-call.update_call(
+call.update_members(
     members=[
         MemberRequest(user_id: 'jack', role: 'admin')
     ]
@@ -210,7 +210,7 @@ For many video calling, live stream, or audio rooms apps, you'll want to show:
 - Calls that are currently live
 - Popular live streams / audio rooms with a link to the recording
 
-Below you can find a few examples of different quieries:
+Below you can find a few examples of different queries:
 
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
@@ -244,31 +244,31 @@ client.video.queryCalls({
 
 ```py
 # default sorting
-call.query_calls(data=QueryCallsRequest())
+client.query_calls()
 
 # sorting and pagination
-response = call.query_calls(
+response = client.query_calls(
     sort= [SortParamRequest(field: 'starts_at', direction: -1)],
     limit=2,
 )
 
 # loading next page
-call.query_calls(
+client.query_calls(
     sort= [SortParamRequest(field: 'starts_at', direction: -1)],
     limit=2,
     next=response.data().next
 )
 
 # filtering
-call.query_calls(
+client.query_calls(
     filter_conditions={'backstage': {'$eq': False}}
 )
 ```
 
 </TabItem>
 </Tabs>
 
-Filter expressions support multiple match criteria and it's also possible to combine filters. For more information visit the [filter operators](https://getstream.io/chat/docs/node/query_syntax_operators/?language=javascript) guide.
+Filter expressions support multiple match criteria, and it's also possible to combine filters. For more information, visit the [filter operators](https://getstream.io/chat/docs/node/query_syntax_operators/?language=javascript) guide.
 
 ## Query call members
 
@@ -328,4 +328,4 @@ call.query_members(
 </TabItem>
 </Tabs>
 
-Filter expressions support multiple match criteria and it's also possible to combine filters. For more information visit the [filter operators](https://getstream.io/chat/docs/node/query_syntax_operators/?language=javascript) guide.
+Filter expressions support multiple match criteria, and it's also possible to combine filters. For more information, visit the [filter operators](https://getstream.io/chat/docs/node/query_syntax_operators/?language=javascript) guide.