tweakio-sdk 0.1.5

Tweakio-SDK: WhatsApp automation Python library with anti-detection, async storage, and production-grade architecture

Tweakio-SDK

Production-Grade WhatsApp Web Automation for Python
Anti-detection browser automation built on Playwright + Camoufox.

Documentation · PyPI · Issues · Contributing

---

🔴 The Problem

WhatsApp automation is broken:

1. Detection & Bans — Standard Selenium/Playwright scripts are fingerprinted and banned within hours
2. Fragile Scripts — When WhatsApp updates its UI, your selectors break. You spend weeks patching instead of building
3. No Production Patterns — Most automation tools are throwaway scripts, not production software with proper architecture
4. Platform Lock-In — Want to add Telegram later? Start from scratch

The industry treats automation as disposable code. We don't.

---

💡 The Solution

Tweakio-SDK is a WhatsApp automation framework built with production-grade patterns:

Problem	Tweakio Solution
Detection	Camoufox + BrowserForge fingerprinting (indistinguishable from humans)
Fragile selectors	Interface-driven architecture — when WhatsApp breaks, only src/WhatsApp/ needs updates
No persistence	Async SQLite storage with background queue workers
No typing	Type-safe dataclasses for Chat and Message objects

Current: WhatsApp Web (v0.1.5)
Roadmap: Telegram (Q2 2026), Instagram (Q3 2026)

---

📦 Installation

pip install tweakio-sdk

Requirements: Python 3.10+, Playwright browsers

# Install Playwright browsers (one-time)
playwright install chromium

---

⚡ Quick Start

Basic: Fetch Chats

import asyncio
from BrowserManager import BrowserManager
from src.WhatsApp.login import Login
from src.WhatsApp.chat_processor import ChatProcessor
from src.WhatsApp.web_ui_config import WebSelectorConfig
from Custom_logger import logger

async def main():
    # 1. Launch anti-detect browser
    browser = BrowserManager(headless=False)
    page = await browser.getPage()
    
    # 2. Initialize UI config and Login
    ui_config = WebSelectorConfig(page=page, log=logger)
    login = Login(page=page, UIConfig=ui_config, log=logger)
    
    # 3. Login (scan QR code on first run)
    await login.login(save_path="./session.json")
    
    # 4. Fetch chats
    chat_processor = ChatProcessor(page=page, UIConfig=ui_config, log=logger)
    async for chat, name in chat_processor.Fetcher(MaxChat=5):
        print(f"📂 Chat: {name}")

asyncio.run(main())

Advanced: Message Processing with Storage

import asyncio
from BrowserManager import BrowserManager
from src.WhatsApp.login import Login
from src.WhatsApp.chat_processor import ChatProcessor
from src.WhatsApp.message_processor import MessageProcessor
from src.WhatsApp.web_ui_config import WebSelectorConfig
from src.StorageDB.sqlite_db import SQLITE_DB
from Custom_logger import logger

async def main():
    # Browser + Login setup (same as above)
    browser = BrowserManager(headless=False)
    page = await browser.getPage()
    ui_config = WebSelectorConfig(page=page, log=logger)
    login = Login(page=page, UIConfig=ui_config, log=logger)
    await login.login(save_path="./session.json")
    
    # Initialize async storage
    queue = asyncio.Queue()
    async with SQLITE_DB(queue=queue, log=logger, db_path="messages.db") as storage:
        
        # Initialize processors
        chat_processor = ChatProcessor(page=page, UIConfig=ui_config, log=logger)
        msg_processor = MessageProcessor(
            page=page,
            UIConfig=ui_config,
            chat_processor=chat_processor,
            log=logger,
            storage=storage  # Messages auto-saved to SQLite
        )
        
        # Fetch and process messages
        async for chat, name in chat_processor.Fetcher(MaxChat=3):
            print(f"📂 Processing: {name}")
            
            # Fetcher returns wrapped Message objects with deduplication
            messages = await msg_processor.Fetcher(chat=chat, retry=3)
            
            for msg in messages:
                print(f"   💬 {msg.data_type}: {msg.raw_data[:50]}...")
                print(f"      ID: {msg.message_id}")
                print(f"      Direction: {msg.direction}")

asyncio.run(main())

---

🏗️ Architecture

tweakio-sdk/
├── src/
│   ├── BrowserManager/     # Anti-detect Playwright + Camoufox
│   ├── WhatsApp/           # Platform-specific implementation
│   │   ├── login.py        # QR + Phone authentication
│   │   ├── chat_processor.py
│   │   ├── message_processor.py
│   │   ├── web_ui_config.py  # Selector definitions
│   │   └── DerivedTypes/   # Chat, Message dataclasses
│   ├── Interfaces/         # Abstract contracts (for future platforms)
│   ├── StorageDB/          # Async SQLite with queue workers
│   └── Exceptions/         # Custom exception hierarchy
└── tests/                  # >90% coverage on core modules

Key Design Decisions

• Interface-Driven: Every platform implements ChatProcessorInterface, MessageProcessorInterface, etc.
• Dependency Injection: All classes accept log parameter for testability
• Async-First: Non-blocking SQLite writes, background queue workers
• Anti-Detection: Camoufox fingerprints + human-like typing delays

---

📊 Modules

Module	Description
BrowserManager	Anti-detect browser with fingerprint rotation
Login	QR code + phone number authentication
ChatProcessor	Fetch chats, handle unread status, click navigation
MessageProcessor	Extract messages, deduplicate, filter, store
SQLITE_DB	Async queue-powered storage with batch inserts
WebSelectorConfig	Platform-specific DOM selectors

---

🛠️ How It Works

Message Processing Flow

1. ChatProcessor.Fetcher() → yields Chat objects
2. MessageProcessor.Fetcher(chat) → clicks chat, extracts messages
3. Messages wrapped as whatsapp_message dataclass
4. New messages enqueued to SQLITE_DB async queue
5. Background writer batches inserts every N seconds

Anti-Detection Stack

Playwright (base) → Camoufox (fingerprint) → BrowserForge (realistic profiles)

---

🤝 Contributing

We welcome contributions! Vibe coding accepted — if it works and is clean, we'll merge it.

Contribution Rules

1. Fork → Branch → PR workflow required
2. AI-Assisted code is welcome — just mention it in your PR description for transparency
3. Tests required for new features (we maintain >90% coverage on core modules)
4. Type hints required — we use mypy for static analysis

Quick Start for Contributors

# Clone and setup
git clone https://github.com/BITS-Rohit/tweakio-sdk.git
cd tweakio-sdk
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest --cov=src

# Your feature branch
git checkout -b feature/your-feature

PR Template

## What does this PR do?
[Description]

## AI Disclosure
- [ ] This PR includes AI-generated code (Claude/GPT/Copilot)
- [ ] This PR is fully human-written

## Testing
- [ ] Added/updated tests
- [ ] All tests pass locally

---

🗺️ Roadmap

v0.1.6 — Core Infrastructure

• Custom Logger improvements
• Multi-Account Handling
• BrowserManager enhancements
• Dependency Injection & Interface renewal
• Directory structure improvements
• Separate Browser Logging

v0.1.7 — Security & Stability

• Encryption & Decryption module
• KeyBox integration
• Stability & Decryptor additions
• Stability increase → 60-70% reliability

v0.1.8 — Quality Assurance

• Test coverage increase & logic improvements
• Web-UI tinkering & refinements

v0.2.0 — Multi-Platform (Coming Soon)

• Another Platform integration (Telegram/Instagram)
• Platform-agnostic architecture

---

❓ FAQ

Q: Will I get banned?
A: Tweakio uses Camoufox anti-detection. With reasonable rate limiting, bans are rare. Always test on disposable accounts first.

Q: Can I use this for spam?
A: No. This SDK is for legitimate automation (customer support, archiving, notifications). Spam violates WhatsApp ToS and is not supported.

Q: Why not just use the WhatsApp Business API?
A: Business API has message template restrictions and approval processes. Tweakio is for developers who need full control.

---

📄 License

MIT License — see LICENSE

---

🔗 Links

• PyPI: pypi.org/project/tweakio-sdk
• GitHub: github.com/BITS-Rohit/tweakio-sdk
• Issues: Report bugs

---

Keywords: tweakio, tweakio-sdk, whatsapp automation, whatsapp bot python, whatsapp api, web automation, playwright, browser automation, chatbot, messaging, anti-detection, camoufox

Built with ❤️ by BITS-Rohit and the Tweakio community