tweakio-sdk 0.1.5__tar.gz

tweakio_sdk-0.1.5/Custom_logger.py

@@ -0,0 +1,54 @@
+"""
+Shared Resources Module for tweakio-sdk library
+"""
+import logging
+from logging.handlers import RotatingFileHandler
+
+from colorlog import ColoredFormatter
+
+import directory as dirs
+
+# ------ Logger Configs ---------
+logger = logging.getLogger("tweakio")
+logger.setLevel(logging.INFO)
+
+# -------------------------------
+# Console handler
+# -------------------------------
+
+console_formatter = ColoredFormatter(
+    "%(log_color)s%(asctime)s | %(levelname)s | %(message)s",
+    log_colors={
+        'DEBUG': 'cyan',
+        'INFO': 'green',
+        'WARNING': 'yellow',
+        'ERROR': 'red',
+        'CRITICAL': 'bold_red'
+    }
+)
+
+console_handler = logging.StreamHandler()
+console_handler.setFormatter(console_formatter)
+logger.addHandler(console_handler)
+
+console_formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
+console_handler.setFormatter(console_formatter)
+logger.addHandler(console_handler)
+
+# -------------------------------
+# File handler with rotation
+# -------------------------------
+file_handler = RotatingFileHandler(
+    dirs.ErrorTrace_file,  # file path
+    maxBytes=20 * 1024 * 1024,  # 20 MB per file
+    backupCount=3  # keep last 3 files
+)
+file_formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
+file_handler.setFormatter(file_formatter)
+logger.addHandler(file_handler)
+
+# -------------------------------
+# General settings
+# -------------------------------
+logger.propagate = False
+

tweakio_sdk-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [BITS-Rohit]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tweakio_sdk-0.1.5/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include *.py
+include requirements.txt
+recursive-include BrowserManager *.py

tweakio_sdk-0.1.5/PKG-INFO

@@ -0,0 +1,342 @@
+Metadata-Version: 2.4
+Name: tweakio-sdk
+Version: 0.1.5
+Summary: Tweakio-SDK: WhatsApp automation Python library with anti-detection, async storage, and production-grade architecture
+Author: Rohit
+Author-email: BITS-Rohit <rohit@tweakio.dev>
+Maintainer-email: BITS-Rohit <rohit@tweakio.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/BITS-Rohit/tweakio-sdk
+Project-URL: Repository, https://github.com/BITS-Rohit/tweakio-sdk
+Project-URL: Documentation, https://github.com/BITS-Rohit/tweakio-sdk#readme
+Project-URL: Issues, https://github.com/BITS-Rohit/tweakio-sdk/issues
+Project-URL: Changelog, https://github.com/BITS-Rohit/tweakio-sdk/releases
+Keywords: tweakio,tweakio-sdk,whatsapp,whatsapp-automation,whatsapp-bot,automation,playwright,web-automation,browser-automation,chatbot,messaging,anti-detection,camoufox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: camoufox>=0.3.0
+Requires-Dist: pyperclip>=1.8.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.0.290; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# Tweakio-SDK
+
+> **Production-Grade WhatsApp Web Automation for Python**  
+> _Anti-detection browser automation built on Playwright + Camoufox._
+
+[![PyPI - Version](https://img.shields.io/pypi/v/tweakio-sdk?label=tweakio-sdk)](https://pypi.org/project/tweakio-sdk/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tweakio-sdk)](https://pypi.org/project/tweakio-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Test Coverage](https://img.shields.io/badge/coverage-%3E90%25-brightgreen)](https://github.com/BITS-Rohit/tweakio-sdk)
+
+**[Documentation](https://github.com/BITS-Rohit/tweakio-sdk#readme)** · **[PyPI](https://pypi.org/project/tweakio-sdk/)** · **[Issues](https://github.com/BITS-Rohit/tweakio-sdk/issues)** · **[Contributing](#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
+
+```bash
+pip install tweakio-sdk
+```
+
+**Requirements**: Python 3.10+, Playwright browsers
+
+```bash
+# Install Playwright browsers (one-time)
+playwright install chromium
+```
+
+---
+
+## ⚡ Quick Start
+
+### Basic: Fetch Chats
+
+```python
+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
+
+```python
+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
+
+```bash
+# 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
+
+```markdown
+## 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](LICENSE)
+
+---
+
+## 🔗 Links
+
+- **PyPI**: [pypi.org/project/tweakio-sdk](https://pypi.org/project/tweakio-sdk/)
+- **GitHub**: [github.com/BITS-Rohit/tweakio-sdk](https://github.com/BITS-Rohit/tweakio-sdk)
+- **Issues**: [Report bugs](https://github.com/BITS-Rohit/tweakio-sdk/issues)
+
+---
+
+**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_