chore(readme): sync documentation with new incoming call feature

README.md

@@ -29,7 +29,7 @@
     <td style="padding: 10px; background-color: #f6f8fa; border-radius: 0 6px 6px 0;">
       Write scripts to automate call flows with your own business logic.
     </td>
-  </tr>
+  </tr> 
   <tr>
     <td style="padding: 10px; background-color: #f6f8fa; font-weight: bold;">
       UDP Transport Layer
@@ -56,8 +56,8 @@
   </tr>
 </table>
 
-
 ## 📚 **Table of Contents**
+
 1. [Installation](#-installation)
 2. [Project Structure](#-project-structure)
 3. [Getting Started](#-getting-started)
@@ -76,24 +76,30 @@
 <div style="background-color: #f6f8fa; border-radius: 6px; padding: 16px;">
 
 ### Step 1: Clone the repository
+
 ```bash
 git clone https://github.com/moha-abdi/PySIP.git
 cd PySIP
 ```
 
 ### Step 2: Install dependencies
+
 Ensure you have Python 3.8+ installed. Install the required dependencies using:
+
 ```bash
 pip install -r requirements.txt
 ```
 
 ### Step 3: Environment Setup
+
 Create a `.env` file to store your SIP account credentials and server details:
+
 ```bash
 SIP_USERNAME=your_sip_username
 SIP_PASSWORD=your_sip_password
 SIP_SERVER=your_sip_server
 ```
+
 </div>
 
 ---
@@ -120,6 +126,7 @@ PySIP/
 ├── .env.example                # Example environment configuration
 └── README.md                   # Project documentation
 ```
+
 </div>
 
 ---
@@ -129,6 +136,7 @@ PySIP/
 <div style="background-color: #f6f8fa; border-radius: 6px; padding: 16px;">
 
 ### Step 1: Setting Up a SIP Account
+
 A SIP account is essential for handling calls. To start, you need to create an instance of the `SipAccount` class, which requires your SIP credentials (username, password, and server). Here's how to do it:
 
 ```python
@@ -147,11 +155,15 @@ account = SipAccount(
 ```
 
 ### Step 2: Registering the Account
+
 Once the `SipAccount` is created, the next step is to register it with the SIP server:
+
 ```python
 await account.register()
 ```
+
 This sends a SIP `REGISTER` request to the server to activate the account. Once registered, you can make calls or listen for incoming calls.
+
 </div>
 
 ---
@@ -165,27 +177,47 @@ This sends a SIP `REGISTER` request to the server to activate the account. Once
 The `SipAccount` class is at the core of PySIP. It handles all account-related tasks such as registration, making calls, and unregistering from the SIP server.
 
 #### **Instantiating a SIP Account**:
+
 ```python
 account = SipAccount(username, password, server)
 ```
 
 #### **Registering**:
+
 Call the `register()` method to register the SIP account with the server:
+
 ```python
 await account.register()
 ```
 
 #### **Making Calls**:
+
 The `make_call(destination)` method initiates a call to the destination number:
+
 ```python
 call = account.make_call("destination_number")
 ```
 
+#### **Handling Incoming Calls**:
+
+Use the `on_incoming_call` decorator to define a function that will handle incoming calls:
+
+```python
+@account.on_incoming_call
+async def handle_incoming_call(call: SipCall):
+    await call.accept()  # or call.reject() or call.busy()
+    await call.call_handler.say("Thank you for calling us!")
+    await call.call_handler.hangup()
+```
+
 #### **Unregistering**:
+
 When you're done, unregister the account to gracefully close the session:
+
 ```python
 await account.unregister()
 ```
+
 </div>
 
 ### Call Handling
@@ -195,21 +227,37 @@ await account.unregister()
 The `CallHandler` is responsible for handling the call flow. It allows you to say messages, gather input from the caller, or transfer the call.
 
 #### **Playing a message to the caller**:
+
 ```python
 await call_handler.say("Welcome to our service.")
 ```
 
 #### **Gathering user input**:
+
 Use `gather()` to gather input from the user, such as pressing a digit:
+
 ```python
 dtmf_key = await call_handler.gather(length=1, timeout=5)
 ```
 
 #### **Transferring the call**:
+
 You can forward the call to another number:
+
 ```python
 await call_handler.transfer_to("1234567890")
 ```
+
+#### **Accepting, Rejecting, or Setting Busy for Incoming Calls**:
+
+For incoming calls, you can use the following methods:
+
+```python
+await call.accept()  # Accept the incoming call
+await call.reject()  # Reject the incoming call
+await call.busy()    # Mark the line as busy for the incoming call
+```
+
 </div>
 
 ### UDP Transport
@@ -219,16 +267,21 @@ await call_handler.transfer_to("1234567890")
 The `UdpHandler` is an internal module that manages the asynchronous sending and receiving of SIP messages over the network.
 
 #### **Sending a message**:
+
 The `send_message()` method sends a UDP message to the SIP server or peer:
+
 ```python
 self.transport.sendto(message)
 ```
 
 #### **Receiving a datagram**:
+
 The `datagram_received()` method handles incoming messages, placing them in a queue for processing:
+
 ```python
 self.data_q.put_nowait(data)
 ```
+
 </div>
 
 ---
@@ -256,6 +309,11 @@ account = SipAccount(
     os.environ["SIP_SERVER"],
 )
 
+@account.on_incoming_call
+async def handle_incoming_call(call: SipCall):
+    await call.accept() 
+    await call.call_handler.say("We have received your call successfully")
+
 async def main():
     # Register the SIP account
     await account.register()
@@ -274,6 +332,7 @@ async def main():
 if __name__ == "__main__":
     asyncio.run(main())
 ```
+
 </div>
 
 ---
@@ -283,6 +342,7 @@ if __name__ == "__main__":
 While the appointment booking bot is just one example, **PySIP** is designed to let you create any SIP-based automation or custom script that fits your needs.
 
 To create your own script:
+
 1. **Create a Python file** in the `scripts/` directory.
 2. **Write your custom call logic** using the `CallHandler` class to control the call flow.
 3. **Use the `SipAccount` to register and make calls** as demonstrated in the example script.
@@ -296,5 +356,5 @@ Contributions are welcome! If you would like to contribute to the development of
 ---
 
 <div style="text-align: center; align: center; margin-top: 30px;" align="center">
-  <p align="center">Made with ❤️ by the Moha Abdi</p>
+  <p align="center">Made with ❤️ by Moha Abdi</p>
 </div>