basic explanations for the Basics sections

docusaurus/video/docusaurus/docs/api/basics/authentication.mdx

@@ -10,18 +10,24 @@ 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.
+
+The `name` and `image` fields are special fields that are supported by client-side SDKs.
+
+You can provide additional data for the user object using the `custom` field.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
 ```js
 const newUser: UserObjectRequest = {
   id: 'userid',
-  role: "user",
+  role: 'user',
   custom: {
-    color: 'red'
+    color: 'red',
   },
   name: 'This is a test user',
-  image: 'link/to/profile/image'
+  image: 'link/to/profile/image',
 };
 await client.upsertUsers({
   users: {
@@ -35,18 +41,23 @@ await client.upsertUsers({
 
 ## Updating users
 
+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
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
 ```js
 const user: UserObjectRequest = {
   id: 'userid',
-  role: "user",
+  role: 'user',
   custom: {
-    color: 'red'
+    color: 'red',
   },
   name: 'This is a test user',
-  image: 'link/to/profile/image'
+  image: 'link/to/profile/image',
 };
 client.upsertUsers({
   users: {
@@ -55,22 +66,71 @@ client.upsertUsers({
 });
 
 // or
-client.updateUsersPartial({users: [
-  {
-    id: user.id,
-	set: {
-	  color: 'blue'
-	},
-	unset: ['name'],
-  }
-]});
+client.updateUsersPartial({
+  users: [
+    {
+      id: user.id,
+      set: {
+        color: 'blue',
+      },
+      unset: ['name'],
+    },
+  ],
+});
 ```
 
 </TabItem>
 </Tabs>
 
+## Anonymous users
+
+Anonymous users are users that are not authenticated. It's common to use this for watching a livestream or similar where you aren't authenticated. Anonymous users can be connected using client-side SDKs.
+
+## 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.
+
+<Tabs groupId="examples">
+<TabItem value="js" label="JavaScript">
+
+```js
+const guest: UserObjectRequest = {
+  id: '<id>',
+  name: '<name>',
+  custom: {
+    color: 'red',
+  },
+};
+
+const guest = (await client.createGuest({ 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.
+
+```js
+client.deactivateUser({
+  user_id: '<id>',
+});
+
+client.deleteUser({ userId: '<id>' });
+```
+
 ## 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.
+
+You can optionally provide
+
+- expiration time
+- issued at date which is necessary if you manually wan to revoke tokens
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -130,6 +190,8 @@ func main() {
 
 ## Call tokens
 
+Call tokens contain a list of call IDs. If a user is authenticated with a call token, they can only access the specified calls.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -142,7 +204,12 @@ 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.createToken(
+  (user_id = user_id),
+  (exp = exp),
+  (iat = iat),
+  (call_cids = call_cids),
+);
 ```
 
 </TabItem>
@@ -192,5 +259,16 @@ func main() {
 
 ## Token expiration and token providers
 
-TODO: explain that tokens should have an expiration
-TODO: mention that in a production environment you have an endpoint to send fresh tokens to users
+At a high level, the Token Provider is an endpoint on your server that can perform the following sequence of tasks:
+
+1. Receive information about a user from the front end.
+
+2. Validate that user information against your system.
+
+3. Provide a User-ID corresponding to that user to the server client's token creation method.
+
+4. Return that token to the front end.
+
+Tokens can only be safely generated from a server. This means you will need to implement a Token Provider prior to deploying your application to production. To conduct development before implementing a Token Provider, you will need to disable token authentication.
+
+Tokens also should have an expiration date to ensure adequate security. Once a token is expired, cliend-side SDKs can automatically call an endpoint to refresh the token, this endpoint should also be part of the Token Provider implementation.

docusaurus/video/docusaurus/docs/api/basics/calls.mdx

@@ -10,6 +10,13 @@ import TabItem from '@theme/TabItem';
 
 ## Creating calls
 
+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.
+- 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.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -47,9 +54,9 @@ call.get_or_create_call(
         created_by_id='john',
         members=[
             MemberRequest(
-                user_id: 'john', 
+                user_id: 'john',
                 role: 'admin'
-			), 
+			),
             MemberRequest(
                 user_id: 'jack'
 			)
@@ -113,11 +120,19 @@ curl -X POST "https://video.stream-io-api.com/video/call/default/${CALL_ID}?api_
 
 ## Updating calls
 
+- Most of the call type settings can be overriden on a call level.
+
+- Custom data can also be stored for calls.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
 ```js
-call.update({ settings_override: { audio: { mic_default_on: true, default_device: "speaker" } } });
+call.update({
+  settings_override: {
+    audio: { mic_default_on: true, default_device: 'speaker' },
+  },
+});
 
 // or to update custom data
 call.update({ custom: { color: 'red' } });
@@ -212,6 +227,8 @@ 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.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -235,7 +252,7 @@ call.updateCallMembers({
 
 call.update_call(
     members=[
-        MemberRequest(user_id: 'sara'), 
+        MemberRequest(user_id: 'sara'),
         MemberRequest(user_id: 'jack', role: 'admin')
     ]
 )
@@ -312,6 +329,14 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}/membe
 
 ## Query calls
 
+For many video calling, live stream, or audio rooms apps, you'll want to show:
+
+- Upcoming calls
+- 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:
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -368,6 +393,8 @@ call.query_calls(
 </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.
+
 ## Query call members
 
 <Tabs groupId="examples">
@@ -425,3 +452,5 @@ 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.

docusaurus/video/docusaurus/docs/api/basics/get_started.mdx

@@ -7,7 +7,13 @@ title: Get started
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
-import RTMP from '../_common_/rtmp.mdx'
+import RTMP from '../_common_/rtmp.mdx';
+
+For the average Stream integration, the development work focuses on code that executes in the client. However, some tasks must be executed from the server for safety (for example token generation).
+
+Stream provides server-side SDKs to help executing these tasks.
+
+You can reference our [development roadmap](https://github.com/GetStream/protocol/discussions/177) to know which languages and features are supported.
 
 ## Installation
 
@@ -39,6 +45,8 @@ go get github.com/GetStream/video-go-sdk
 
 ## Creating client
 
+To create a server-side client you'll need your **API key** and **secret**, both of them can be found in your [Stream Dashboard](https://dashboard.getstream.io/).
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -75,6 +83,8 @@ TODO
 
 ## Creating user tokens
 
+Tokens need to be generated server-side. Typically you integrate this into the part of your codebase where you login or register users. The tokens provide a way to authenticate a user or give access to a specific set of video/audio calls.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -130,6 +140,13 @@ func main() {
 
 ## Creating a call
 
+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.
+- 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.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -299,11 +316,19 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}/membe
 
 ## Updating a call
 
+- Most of the call type settings can be overriden on a call level.
+
+- Custom data can also be stored for calls.
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
 ```js
-call.update({ settings_override: { audio: { mic_default_on: true, default_device: "speaker" } } });
+call.update({
+  settings_override: {
+    audio: { mic_default_on: true, default_device: 'speaker' },
+  },
+});
 
 // or to update custom data
 call.update({ custom: { color: 'red' } });
@@ -396,6 +421,17 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}?api_k
 
 ## Start HLS broadcasting
 
+Broadcasting serves are a means of transmitting live or pre-recorded content to a wide audience.
+
+We can choose from two approaches to broadcasting the media:
+
+- [HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) - slight delay, better buffering
+- [WebRTC](https://webrtc.org/) - lower latency, less reliability
+
+It is up to the integrators to decide, what approach will be used in their apps for the audience to consume the streams.
+
+For more information see the [Streaming section](streaming/overview/).
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -473,10 +509,16 @@ curl -X POST "https://video.stream-io-api.com/video/call/default/${CALL_ID}/star
 
 ## Set up a call for RTMP
 
-<RTMP/>
+Almost all livestream software and hardware supports RTMPS. Our API supports using a third-party software for streaming using RTMPS. For more information reference the [Streaming section](streaming/overview/).
+
+<RTMP />
 
 ## Start call recording
 
+Calls can be recorded for later use. Calls recording can be started/stopped via API calls or configured to start automatically when the first user joins the call.
+
+For more information see the [Recordings section](recording/calls/).
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">