Metadata-Version: 2.4
Name: karboai.py
Version: 1.0.3
Summary: A fast, fully-featured wrapper for the KarboAI API with bot support
Home-page: https://github.com/Exti0/karboai.py
Author: Adham (@Exti0)
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: frida>=16.0.0
Requires-Dist: frida-tools>=12.0.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">
  <h1>🤖 KarboAI Python Library</h1>
  <p><strong>A fast, fully-featured, and asynchronous-ready wrapper for the KarboAI API</strong></p>
  <p><i>Made By: Adham (@Exti0)</i></p>

  <p>
    <a href="https://pypi.org/project/karboai.py/"><img src="https://img.shields.io/pypi/v/karboai.py.svg?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI version"></a>
    <a href="https://pypi.org/project/karboai.py/"><img src="https://img.shields.io/pypi/pyversions/karboai.py.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python Versions"></a>
    <a href="https://pypi.org/project/karboai.py/"><img src="https://img.shields.io/pypi/dm/karboai.py.svg?style=for-the-badge" alt="PyPI Downloads"></a>
    <a href="https://t.me/hackerngia"><img src="https://img.shields.io/badge/Telegram-Channel-blue?style=for-the-badge&logo=telegram" alt="Telegram Channel"></a>
    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="License: MIT"></a>
  </p>
</div>

> [!WARNING]
> **Work In Progress:** This library is not yet 100% complete. Many endpoints and features are still being added, and future updates will bring more functionality!

---

## ⚡ Features

- **🚀 Ultra-Fast Bot Framework:** Built-in decorators (`@bot.on_message()`) and concurrent polling make building ultra-fast bots a breeze.
- **⚡ Concurrent Processing:** Uses `ThreadPoolExecutor` to handle multiple chats and messages simultaneously without blocking.
- **🛡️ Auto-Signature Generation:** Dynamically and seamlessly generates request signatures by natively hooking the Karbo app via Frida.

---

## 🛠️ Installation & Setup

1. Install the library directly from PyPI:
   ```bash
   pip install karboai.py
   ```
2. Ensure you have Python 3.8+ installed.
3. **Frida Server:** You must have `frida-server` installed and running on your rooted Android device or emulator. The `frida-server` version **must exactly match** the `frida` and `frida-tools` versions installed via pip.
4. Make sure your Android device is connected via ADB and the Karbo app is running.
5. Import the library (`import karboai`). Required dependencies will install automatically.
6. **Authentication:** Currently, there is no auto-login. You must extract your `token` and `device-id` manually (e.g. via packet capture like HttpCanary or PCAPdroid) and pass them to `client.login()`.

---

## 🚀 Quick Start (Bot Example)

This is a minimal example of how to start a bot that listens to a chat and responds to messages.

```python
from karboai import KarboClient, KarboBot, enable_debug

# 1. Enable debug mode if you want to see all API requests/responses in the terminal
# enable_debug()

# 2. Initialize and authenticate
client = KarboClient()
client.login(
    token="YOUR_ACCOUNT_TOKEN",
    device_id="YOUR_DEVICE_ID"
)

# 3. Initialize the Bot
bot = KarboBot(client)

# Prevent the bot from getting stuck in an infinite loop replying to itself
bot.set_bot_identity(nickname="TestingBot", user_id="BOT_USER_ID")

# 4. Create your message handler
@bot.on_message()
def handle_messages(msg, chat_id):
    content = msg.content.strip()
    author_name = msg.author.nickname if msg.author else "Unknown"

    print(f"New message from {author_name}: {content}")

    if content == "!ping":
        bot.reply(chat_id, "Pong! 🏓", community_id=15, reply_to_message_id=msg.messageId)

# 5. Start polling your chats
CHATS_TO_MONITOR = [
    "YOUR_CHAT_UUID_HERE"
]

print("Starting bot...")
bot.start_polling(CHATS_TO_MONITOR, interval=1.0)
```

---

## 📖 API Reference

### 1. `KarboClient`

The `KarboClient` handles authentication and the core API requests.

#### Authentication

- `login(token: str, device_id: str, user_agent: str = None)`
  Authenticates your session.
- `logout()`
  Clears current authentication.
- `is_authenticated` (property)
  Returns `True` if logged in.

#### Chat Methods

- `get_my_chats(limit=25, offset=0)`
  Returns a list of `Chat` objects representing your active chats.
- `get_chat(chat_id: str)`
  Returns a `Chat` object representing the details of a specific chat.
- `send_message(chat_id: str, content: str, community_id: int, reply_message_id: str = None)`
  Sends a message to the specified chat.
- `start_dm(target_user_id: str, community_id: int)`
  Initiates a Direct Message with another user. Returns a `Chat` object.
- `get_chat_members(chat_id: str, community_id: int, limit=100, offset=0)`
  Returns a dictionary containing `items` (List of `ChatMember`), `has_more` (bool), and `total_count` (int).

#### Community Methods

- `get_my_community(limit=30, offset=0)`
  Returns a list of your communities.
- `get_featured_communities(limit=10)`
  Returns featured communities.
- `get_community_online(community_id: int)`
  Returns online members and stats for a community.

#### Miscellaneous Methods

- `get_shop_status()`
  Returns a `ShopStatus` object.
- `get_privacy()`
  Returns the user's DM privacy settings.

---

### 2. `KarboBot`

The `KarboBot` simplifies message handling and polling.

- `__init__(client: KarboClient)`
  Initializes the bot with an authenticated client.
- `set_bot_identity(nickname: str = None, user_id: str = None)`
  Registers the bot's username or ID so it doesn't process its own messages.
- `@bot.on_message()`
  A decorator used to register a function to handle incoming messages.
  Your function must accept two arguments: `(msg: Message, chat_id: str)`.
- `reply(chat_id: str, text: str, community_id: int, reply_to_message_id: str = None)`
  A convenience method to send a reply quickly from within your message handler.
- `start_polling(chat_ids: List[str], interval: float = 1.0)`
  Starts the infinite loop to concurrently poll the provided `chat_ids`.
- `stop()`
  Gracefully stops the polling loop.

---

### 3. Debugging Tools (`karboai.banner`)

The library includes built-in colorful debugging tools designed to give you a hacker-style terminal view of everything happening in the background.

- `enable_debug()`
  Turns on verbose logging. You will see every HTTP method, URL, Headers, and raw JSON response printed to the terminal.
- `disable_debug()`
  Turns off verbose logging.

---

## 🔧 Troubleshooting / FAQ

**Q: I'm getting `SignatureError` or `FridaError`!**
A: Ensure your Android device/emulator is connected via ADB and that the Karbo app is currently running in the foreground or background. The script uses Frida to extract signatures locally directly from the app's Java classes.

**Q: The bot is replying to itself endlessly!**
A: Use `bot.set_bot_identity(nickname="YourBotName")` before you call `bot.start_polling()`.

**Q: Can I run multiple handlers at once?**
A: Yes! You can use the `@bot.on_message()` decorator on as many functions as you want. The bot uses a ThreadPoolExecutor to run them concurrently.
