wip(docs): update upload, webhook, auth, intro

Author: f.fallah

docs/en/auth.md

@@ -1,130 +1,73 @@
 # Authentication Guide
 
-The Basalam Python SDK supports multiple authentication methods to suit different use cases. This guide covers all available authentication options with practical examples.
+The SDK supports three main authentication methods, all managed via authentication objects implementing the `BaseAuth` interface:
 
-All authentication is handled through authentication objects that implement the `BaseAuth` interface. The SDK supports three main authentication methods:
+- **Personal Access Token** – for personal or dedicated applications
+- **Authorization Code Flow** – for user authentication scenarios on third-party platforms
+- **Client Credentials** – for applications with legal/organizational access
 
-1. **Personal Token** - For applications with existing tokens
-2. **Authorization Code Flow** - For user authentication scenarios
-3. **Client Credentials** - For server-to-server applications
+For more information about these methods, refer to the [Authentication in Basalam API](../../quick-start#auth) document.
 
 ## Table of Contents
 
-- [Personal Token](#personal-token-for-existing-tokens)
+- [Personal Access Token](#personal-access-token)
 - [Authorization Code Flow](#authorization-code-flow-for-user-authentication)
-- [Client Credentials](#client-credentials-recommended-for-server-to-server)
+- [Client Credentials](#client-credentials)
 - [Token Management](#token-management)
 - [Scopes](#scopes)
 
-## Personal Token (For Existing Tokens)
+## Personal Access Token
 
-Use this method when you already have valid access and refresh tokens.
-
-### Basic Usage
+For personal applications for a booth or user, after [getting your token from the developer panel](https://developers.basalam.com/panel/tokens), you can manage it using `PersonalToken`.
 
 ```python
 from basalam_sdk import BasalamClient, PersonalToken
 
-# Initialize with existing tokens
-auth = PersonalToken(
-    token="your_existing_access_token",
-    refresh_token="your_existing_refresh_token"
-)
-
-# Create authenticated client
-client = BasalamClient(auth=auth)
-```
-
-### Advanced Configuration
-
-```python
-from basalam_sdk import PersonalToken, BasalamConfig
-
-config = BasalamConfig(
-    base_url="https://api.basalam.com",
-    timeout=30
-)
-
-auth = PersonalToken(
-    token="your_access_token",
-    refresh_token="your_refresh_token",
-    token_type="Bearer",
-    expires_in=7200,  # 2 hours
-    scope="customer.wallet.read vendor.product.write",
-    config=config
-)
-
-client = BasalamClient(auth=auth)
-```
-
-### Usage Example
-
-```python
-async def personal_token_example():
+def personal_token_example():
+    # Initialize with existing tokens
     auth = PersonalToken(
         token="your_access_token",
         refresh_token="your_refresh_token",
-        expires_in=3600
     )
-    
+
+    # Create an authenticated client
     client = BasalamClient(auth=auth)
-    
-    # Use the client normally
-    balance = await client.get_balance(user_id=123)
-    return balance
-```
 
-## Authorization Code Flow (For User Authentication)
+    # Get current user info
+    user = client.get_current_user()
+    return user
+```
 
-Use this method when you need to authenticate on behalf of a user.
+## Authorization Code Flow (for user authentication)
 
-### Step-by-Step Process
+When building a third-party app requiring access from users, after [creating a client in the developer panel](https://developers.basalam.com/panel/clients), use the `AuthorizationCode` class to manage the flow.
 
 ```python
 from basalam_sdk import BasalamClient, AuthorizationCode, Scope
 
-# Step 1: Create auth object
+# Step 1: Create the auth object
 auth = AuthorizationCode(
     client_id="your-client-id",
     client_secret="your-client-secret",
     redirect_uri="https://your-app.com/callback",
-    scopes=[Scope.CUSTOMER_WALLET_READ, Scope.CUSTOMER_ORDER_READ]
+    scopes=[
+        Scope.CUSTOMER_WALLET_READ,
+        Scope.CUSTOMER_ORDER_READ
+    ]
 )
 
 # Step 2: Get authorization URL
 auth_url = auth.get_authorization_url(state="optional_state_parameter")
 print(f"Visit: {auth_url}")
 
-# Step 3: Exchange code for tokens (after user authorization)
-token_info = await auth.get_token(code="authorization_code_from_callback")
+# Step 3: Exchange code for tokens (after receiving the code from the registered redirect URI)
+token_info = auth.get_token(code="authorization_code_from_callback")
 
-# Step 4: Create authenticated client
+# Step 4: Create an authenticated client
 client = BasalamClient(auth=auth)
 ```
 
-### Simplified Flow
-
-```python
-async def auth_code_example():
-    # One-step token retrieval
-    auth = AuthorizationCode(
-        client_id="your-client-id",
-        client_secret="your-client-secret",
-        redirect_uri="https://your-app.com/callback"
-    )
-    
-    # Directly get token with authorization code
-    token_info = await auth.get_token(code="your_authorization_code")
-    
-    # The auth object now has the token and can be used with BasalamClient
-    client = BasalamClient(auth=auth)
-    
-    # Use the client
-    balance = await client.get_balance(user_id=123)
-    return balance
-```
-
-### Web Application Example
+### Usage Example
 
 ```python
 from flask import Flask, request, redirect
@@ -138,134 +81,93 @@ def login():
         client_secret="your-client-secret",
         redirect_uri="https://your-app.com/callback"
     )
-    
+
     auth_url = auth.get_authorization_url(state="user_session_id")
     return redirect(auth_url)
 
 @app.route('/callback')
 async def callback():
     code = request.args.get('code')
     state = request.args.get('state')
-    
+
     auth = AuthorizationCode(
         client_id="your-client-id",
         client_secret="your-client-secret",
         redirect_uri="https://your-app.com/callback"
     )
-    
+
     # Exchange code for tokens
     token_info = await auth.get_token(code=code)
-    
-    # Store tokens securely
-    # ... store token_info.access_token, token_info.refresh_token
-    
+
+    # Securely store tokens
+    # ... save token_info.access_token, token_info.refresh_token
+
     return "Authentication successful!"
 ```
 
-## Client Credentials (Recommended for Server-to-Server)
+## Client Credentials
 
-Use this method for server-to-server applications where you have a client ID and secret.
+To use APIs requiring organizational identity (e.g., Wallet), after [client authentication](../../quick-start#client_credentials) using `grant_type="client_credentials"`, use `ClientCredentials`.
 
-### Basic Setup
+### Initial Configuration
 
 ```python
 from basalam_sdk import BasalamClient, ClientCredentials
 
 # Basic authentication
-auth = ClientCredentials(
-    client_id="your-client-id",
-    client_secret="your-client-secret"
-)
-
-# Create client
-client = BasalamClient(auth=auth)
-```
-
-### With Specific Scopes
-
-```python
-from basalam_sdk import ClientCredentials, Scope
-
-# With specific scopes
 auth = ClientCredentials(
     client_id="your-client-id",
     client_secret="your-client-secret",
-    scopes=[Scope.CUSTOMER_WALLET_READ, Scope.VENDOR_PRODUCT_WRITE]
+    scopes=[
+        Scope.CUSTOMER_WALLET_READ,
+        Scope.VENDOR_PRODUCT_WRITE
+    ]
 )
 
+# Create client
 client = BasalamClient(auth=auth)
 ```
 
 ### Usage Example
 
 ```python
+from basalam_sdk import BasalamClient, ClientCredentials
+
 async def client_credentials_example():
     auth = ClientCredentials(
         client_id="your-client-id",
         client_secret="your-client-secret"
     )
     client = BasalamClient(auth=auth)
-    
+
     # Get user balance
     balance = await client.get_balance(user_id=123)
-    
-    # Create webhook
-    webhook = await client.create_webhook({
-        "url": "https://your-app.com/webhook",
-        "events": ["order.created"]
-    })
-    
-    return balance, webhook
+
+    return balance
 ```
 
 ## Token Management
 
-All authentication methods support intelligent token management.
-
-### Get Token Information
+### Get Token Info
 
 ```python
+from basalam_sdk import BasalamClient, ClientCredentials
+
 async def token_management_example():
     auth = ClientCredentials(
         client_id="your-client-id",
         client_secret="your-client-secret"
     )
-    
-    # Get token - will reuse existing token if not expired
-    token_info = await auth.get_token()
-    
-    # Check token status
-    if auth.token_info:
-        print(f"Token expires at: {auth.token_info.expires_at}")
-        print(f"Is expired: {auth.token_info.is_expired}")
-        print(f"Should refresh: {auth.token_info.should_refresh}")
-        print(f"Granted scopes: {list(auth.token_info.granted_scopes)}")
-    
-    return token_info
-```
 
-### Token Refresh
+    # Get token – will reuse existing one if not expired
+    token_info = await auth.get_token()
 
-```python
-async def refresh_token_example():
-    auth = AuthorizationCode(
-        client_id="your-client-id",
-        client_secret="your-client-secret",
-        redirect_uri="https://your-app.com/callback"
-    )
-    
-    # Get initial token
-    await auth.get_token(code="authorization_code")
-    
-    # Later, refresh the token
-    refreshed_token = await auth.get_token()
-    
-    return refreshed_token
+    return token_info
 ```
 
 ## Scopes
 
-Scopes define what permissions your application has. Available scopes include:
+Scopes define the permissions granted to your app. In addition to the [Scopes doc](https://developers.basalam.com/scopes), the SDK provides scopes via the `Scope` class. Available scopes include:
 
 ```python
 from basalam_sdk import Scope
@@ -293,9 +195,4 @@ auth = ClientCredentials(
         Scope.CUSTOMER_ORDER_READ
     ]
 )
-```
-
-## Next Steps
-
-- [Wallet Service](./services/wallet.md) - Manage user balances
-- [Webhook Service](./services/webhook.md) - Handle webhook subscriptions 
+```