nomix-clicker 0.1.0__tar.gz

nomix_clicker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timofey Ivanenko
+
+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.

nomix_clicker-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: nomix-clicker
+Version: 0.1.0
+Summary: iOS device automation via the Nomix Clicker API — simulated touch input with AI screen recognition.
+Author: Timofey Ivanenko
+License-Expression: MIT
+Project-URL: Homepage, https://panel.nomixclicker.com
+Project-URL: Documentation, https://panel.nomixclicker.com/docs
+Project-URL: Repository, https://github.com/timofeyivanenko/ClickerScriptingLibrary
+Keywords: automation,ios,clicker,nomix,ui-automation,device-automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+## NomixClicker Scripting Library
+
+This is a library of ready-made scripts written in Python and using the free [Clicker API](https://panel.nomixclicker.com/docs).
+
+### What Is Clicker?
+
+NomixClicker is a controlling dongle for iOS. It allows manual control, automatic control via API, and fully autonomous AI mode.
+
+Part of the features are work-in-progress, see the [Roadmap](https://nomixclicker.com/).
+
+<p align="center">
+  <img src="res/reddit-script-example.gif" width="480" height="360">
+  <br>
+  <em style="font-size: 0.85em; opacity: 0.7;">Example: quick script for Reddit warmup.</em>
+</p>
+
+### Installation
+
+Requires Python 3.10+. Install from PyPI:
+
+```commandline
+pip install nomix-clicker
+```
+
+Buy a Clicker device if you don't have it (delivery takes ~2 weeks to any place in the world), then open the [Panel](https://panel.nomixclicker.com/choose_device) and get your API token.
+
+[Purchase on the official site only.](https://panel.nomixclicker.com/payment)
+
+### Configuration
+
+Provide your API token and device id in either of two ways (environment variables take precedence):
+
+**Environment variables:**
+
+```commandline
+export NOMIX_API_KEY="your-api-key"
+export NOMIX_DEVICE_ID="your-device-id"
+```
+
+**Or a `config.json`** in your working directory (copy `config.example.json`):
+
+```json
+{
+  "API_KEY": "your-api-key",
+  "DEVICE_ID": "your-device-id",
+  "API_URL": "https://panel.nomixclicker.com/clicker/v1"
+}
+```
+
+### Quick start
+
+```python
+from nomix_clicker import Clicker, parse_screen, open_app, DEVICE_ID
+
+clicker = Clicker(DEVICE_ID)
+open_app(clicker, "Instagram")
+
+screen = parse_screen(clicker)
+screen.find_and_click(clicker, "like")
+```
+
+Manual control of iPhones will work out-of-the-box, no setup needed.
+
+### Examples
+
+Ready-made example scripts live in the [`examples/`](examples/) folder. After installing the package, run one directly, for example:
+
+```commandline
+python3 examples/airplane-mode-iphone-12.py
+```
+
+- [**instagram-warmup.py**](examples/instagram-warmup.py) - Scrolling Instagram Reels, liking, and commenting with configurable probabilities.
+- [**restart_all_devices.py**](examples/restart_all_devices.py) - Restarts all devices associated with your account.
+- [**airplane-mode-iphone-12.py**](examples/airplane-mode-iphone-12.py) - Toggles airplane mode on and off on iPhone 12.
+- [**switch-screen-viewing-iphone-12.py**](examples/switch-screen-viewing-iphone-12.py) - Turns on/off Clicker screen viewing.
+
+### Local development
+
+To work on the library itself, install it in editable mode:
+
+```commandline
+pip install -e .
+```
+

nomix_clicker-0.1.0/README.md

@@ -0,0 +1,84 @@
+## NomixClicker Scripting Library
+
+This is a library of ready-made scripts written in Python and using the free [Clicker API](https://panel.nomixclicker.com/docs).
+
+### What Is Clicker?
+
+NomixClicker is a controlling dongle for iOS. It allows manual control, automatic control via API, and fully autonomous AI mode.
+
+Part of the features are work-in-progress, see the [Roadmap](https://nomixclicker.com/).
+
+<p align="center">
+  <img src="res/reddit-script-example.gif" width="480" height="360">
+  <br>
+  <em style="font-size: 0.85em; opacity: 0.7;">Example: quick script for Reddit warmup.</em>
+</p>
+
+### Installation
+
+Requires Python 3.10+. Install from PyPI:
+
+```commandline
+pip install nomix-clicker
+```
+
+Buy a Clicker device if you don't have it (delivery takes ~2 weeks to any place in the world), then open the [Panel](https://panel.nomixclicker.com/choose_device) and get your API token.
+
+[Purchase on the official site only.](https://panel.nomixclicker.com/payment)
+
+### Configuration
+
+Provide your API token and device id in either of two ways (environment variables take precedence):
+
+**Environment variables:**
+
+```commandline
+export NOMIX_API_KEY="your-api-key"
+export NOMIX_DEVICE_ID="your-device-id"
+```
+
+**Or a `config.json`** in your working directory (copy `config.example.json`):
+
+```json
+{
+  "API_KEY": "your-api-key",
+  "DEVICE_ID": "your-device-id",
+  "API_URL": "https://panel.nomixclicker.com/clicker/v1"
+}
+```
+
+### Quick start
+
+```python
+from nomix_clicker import Clicker, parse_screen, open_app, DEVICE_ID
+
+clicker = Clicker(DEVICE_ID)
+open_app(clicker, "Instagram")
+
+screen = parse_screen(clicker)
+screen.find_and_click(clicker, "like")
+```
+
+Manual control of iPhones will work out-of-the-box, no setup needed.
+
+### Examples
+
+Ready-made example scripts live in the [`examples/`](examples/) folder. After installing the package, run one directly, for example:
+
+```commandline
+python3 examples/airplane-mode-iphone-12.py
+```
+
+- [**instagram-warmup.py**](examples/instagram-warmup.py) - Scrolling Instagram Reels, liking, and commenting with configurable probabilities.
+- [**restart_all_devices.py**](examples/restart_all_devices.py) - Restarts all devices associated with your account.
+- [**airplane-mode-iphone-12.py**](examples/airplane-mode-iphone-12.py) - Toggles airplane mode on and off on iPhone 12.
+- [**switch-screen-viewing-iphone-12.py**](examples/switch-screen-viewing-iphone-12.py) - Turns on/off Clicker screen viewing.
+
+### Local development
+
+To work on the library itself, install it in editable mode:
+
+```commandline
+pip install -e .
+```
+

nomix_clicker-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nomix-clicker"
+version = "0.1.0"
+description = "iOS device automation via the Nomix Clicker API — simulated touch input with AI screen recognition."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Timofey Ivanenko" }]
+keywords = ["automation", "ios", "clicker", "nomix", "ui-automation", "device-automation"]
+dependencies = ["requests>=2.32"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "build>=1.0"]
+
+[project.urls]
+Homepage = "https://panel.nomixclicker.com"
+Documentation = "https://panel.nomixclicker.com/docs"
+Repository = "https://github.com/timofeyivanenko/ClickerScriptingLibrary"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nomix_clicker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nomix_clicker-0.1.0/src/nomix_clicker/__init__.py

@@ -0,0 +1,52 @@
+"""nomix_clicker — iOS device automation via the Nomix Clicker API.
+
+Simulate touch input and use AI screen recognition to navigate apps.
+
+    from nomix_clicker import Clicker, parse_screen, open_app
+
+    clicker = Clicker("your-device-id")
+    open_app(clicker, "Instagram")
+    screen = parse_screen(clicker)
+"""
+
+from .actions import (
+    chance_tap,
+    close_app,
+    find_and_click,
+    is_ad,
+    open_app,
+    post_comment,
+    random_sleep,
+    swipe_back,
+    swipe_feed,
+)
+from .agent import Agent
+from .clicker import Clicker
+from .environment import API_KEY, API_URL, DEVICE_ID
+from .recognition import Element, Screen, parse_screen
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # core
+    "Clicker",
+    "Agent",
+    "Screen",
+    "Element",
+    "parse_screen",
+    # actions
+    "open_app",
+    "close_app",
+    "find_and_click",
+    "swipe_feed",
+    "swipe_back",
+    "is_ad",
+    "chance_tap",
+    "post_comment",
+    "random_sleep",
+    # config
+    "API_URL",
+    "API_KEY",
+    "DEVICE_ID",
+    "__version__",
+]

nomix_clicker-0.1.0/src/nomix_clicker/actions.py

@@ -0,0 +1,184 @@
+import random
+from time import sleep
+from typing import Optional
+
+from .clicker import Clicker
+from .recognition import Screen, parse_screen
+
+COMMENT_SECTION_KEYWORDS = [
+    "close comments",
+    "filter comments",
+    "add comment",
+    "add a comment",
+    "join the conversation",
+]
+
+
+def open_app(clicker: Clicker, app_name: str, retries: int = 3) -> Optional[Screen]:
+    """Open any app via iOS Spotlight search. Retries up to `retries` times.
+
+    Returns the parsed screen on success, or None on failure.
+    """
+    for attempt in range(1, retries + 1):
+        print(f"Opening Spotlight (attempt {attempt}/{retries})...")
+        clicker.swipe((16000, 10000), down=8000, duration=300)
+        sleep(0.5)
+
+        print(f"Typing '{app_name}'...")
+        clicker.type(app_name)
+        sleep(2)
+
+        screen = parse_screen(clicker)
+        if not screen or not screen.find_and_click(clicker, app_name):
+            print(f"WARNING: '{app_name}' not found in Spotlight results")
+            close_app(clicker)
+            continue
+
+        sleep(3)
+
+        screen = parse_screen(clicker)
+        if screen and app_name.lower() in screen.app_name.lower():
+            return screen
+
+        print(f"WARNING: '{app_name}' did not open (current app: '{screen.app_name if screen else 'None'}')")
+        close_app(clicker)
+
+    print(f"ERROR: Failed to open '{app_name}' after {retries} attempts.")
+    return None
+
+
+def _do_close_app(clicker: Clicker) -> None:
+    # Slow swipe up from bottom edge to open app switcher
+    sleep(1)
+    clicker.swipe((16384, 32767), up=4767, duration=1000)
+    sleep(5)
+    # Swipe up on the last app card to dismiss it
+    clicker.swipe((26500, 20000), up=10000, duration=300)
+    sleep(5)
+    # Tap home area to exit app switcher
+    clicker.click((16384, 30000), duration=100)
+
+
+def close_app(clicker: Clicker, retries: int = 3) -> bool:
+    """Open app switcher, dismiss the last app, then tap home.
+
+    Verifies the device returned to the Home Screen after closing.
+    Retries up to `retries` times if the app is still in the foreground.
+    Returns True if the Home Screen is confirmed, False otherwise.
+    """
+    for attempt in range(1, retries + 1):
+        print(f"Closing app (attempt {attempt}/{retries})...")
+        _do_close_app(clicker)
+        sleep(3)
+        screen = parse_screen(clicker)
+        if not screen or screen.app_name.lower() == "home screen":
+            print("App closed successfully.")
+            return True
+        print(f"App still open after attempt {attempt} (screen: '{screen.app_name}'), retrying...")
+    print(f"Warning: could not confirm app was closed after {retries} attempts.")
+    return False
+
+
+_AD_KEYWORDS = [
+    "advertising", "advertisement", "sponsored",
+    "contact us", "shop now", "learn more",
+    "install now", "send message", "get quote",
+]
+
+
+def is_ad(screen: Screen) -> bool:
+    """Return True if the current screen looks like an ad."""
+    return (screen.contains(*_AD_KEYWORDS)
+            or any(el.content.lower() == "ad" for el in screen.elements))
+
+
+def is_comment_section_opened(screen: Screen) -> bool:
+    """Return True if the comments sheet is currently pulled up."""
+    return screen.contains(*COMMENT_SECTION_KEYWORDS)
+
+
+def chance_tap(clicker: Clicker, screen: Screen, name: str, chance: float) -> bool:
+    """Roll the dice and tap a button found on screen. Returns True if tapped."""
+    if random.random() >= chance:
+        return False
+    return screen.find_and_click(clicker, name)
+
+
+def random_sleep(min_s: float = 0.3, max_s: float = 0.8) -> None:
+    """Sleep for a random duration to simulate human behavior."""
+    sleep(random.uniform(min_s, max_s))
+
+
+def swipe_back(clicker: Clicker) -> None:
+    """iOS swipe-back gesture (swipe right from left edge)."""
+    clicker.swipe((5000, 16000), right=20000, duration=300)
+
+
+def swipe_feed(clicker: Clicker) -> None:
+    """Swipe up to the next feed item."""
+    clicker.swipe((16383, 26213), up=6553, duration=100)
+
+
+def find_and_click(clicker: Clicker, *keywords: str, interactive_only: bool = True) -> bool:
+    """Get screen, find element by keywords, and click it. Returns True if clicked."""
+    screen = parse_screen(clicker)
+    if not screen:
+        return False
+    return screen.find_and_click(clicker, *keywords, interactive_only=interactive_only)
+
+
+def post_comment(
+        clicker: Clicker,
+        text: str,
+        input_keywords: list[str],
+        submit_keyword: str | list[str],
+        cached_coords: Optional[dict] = None,
+) -> bool:
+    """Find a comment input field, type text, and submit.
+
+    On the first call, parses the screen twice: once to find the input field,
+    and again after typing to find the send button (which only appears once the
+    keyboard is open). Coords are stored in `cached_coords` so subsequent calls
+    skip both parses entirely.
+    """
+    if cached_coords and "comment_input" in cached_coords and "comment_submit" in cached_coords:
+        clicker.click(cached_coords["comment_input"])
+        clicker.type(text)
+        sleep(0.5)
+        clicker.click(cached_coords["comment_submit"])
+        return True
+
+    screen = parse_screen(clicker)
+    if not screen:
+        return False
+
+    input_coords = screen.find(*input_keywords, interactive_only=False)
+    if not input_coords:
+        print("WARNING: Comment input not found")
+        return False
+
+    clicker.click(input_coords)
+    clicker.type(text)
+    sleep(1)
+
+    screen = parse_screen(clicker)
+    if not screen:
+        return False
+
+    keywords = submit_keyword if isinstance(submit_keyword, list) else [submit_keyword]
+    submit_coords = screen.find(*keywords, interactive_only=False)
+    if not submit_coords:
+        print(f"WARNING: Submit button not found, elements: {[e.content for e in screen.elements]}")
+        return False
+
+    if cached_coords is not None:
+        cached_coords["comment_input"] = input_coords
+        cached_coords["comment_submit"] = submit_coords
+        print(f"Cached comment_input at {input_coords}, comment_submit at {submit_coords}")
+
+    clicker.click(submit_coords)
+    sleep(1)
+    clicker.click((16383, 4096))  # dismiss comments sheet
+    sleep(0.5)
+
+    return True

nomix_clicker-0.1.0/src/nomix_clicker/agent.py

@@ -0,0 +1,78 @@
+import time
+
+from .api_helper import run_agent, get_agent_task, cancel_agent_task
+
+
+class Agent:
+    """AI agent controller for a device."""
+
+    def __init__(self, device_id: str):
+        self.device_id = device_id
+        self.current_task_id: str | None = None
+
+    def execute(self, task: str) -> str:
+        """Start a new agent task. Returns task_id and stores it internally."""
+        result = run_agent(self.device_id, task)
+        task_id = result.get("task_id")
+        if not task_id:
+            raise ValueError(f"API response missing 'task_id': {result}")
+        self.current_task_id = task_id
+        return self.current_task_id
+
+    def get_status(self, task_id: str | None = None) -> dict:
+        """Get task status. Uses current_task_id if none provided."""
+        tid = task_id or self.current_task_id
+        if not tid:
+            raise ValueError("No task_id -- call execute() first or pass task_id")
+        return get_agent_task(self.device_id, tid)
+
+    def cancel(self, task_id: str | None = None) -> dict:
+        """Cancel a running task."""
+        tid = task_id or self.current_task_id
+        if not tid:
+            raise ValueError("No task_id -- call execute() first or pass task_id")
+        result = cancel_agent_task(self.device_id, tid)
+        if tid == self.current_task_id:
+            self.current_task_id = None
+        return result
+
+    def poll(
+        self,
+        task_id: str | None = None,
+        interval: float = 1.0,
+    ) -> str | None:
+        """Poll task until completion, printing events to stdout."""
+        tid = task_id or self.current_task_id
+        if not tid:
+            raise ValueError("No task_id -- call execute() first or pass task_id")
+
+        seen_events = 0
+        while True:
+            task = get_agent_task(self.device_id, tid)
+            events = task.get("events", [])
+
+            for event in events[seen_events:]:
+                step = event.get("step", "?")
+                max_steps = event.get("max_steps", "?")
+                action = event.get("action", "?")
+                result = event.get("result", "?")
+                print(f"[{step}/{max_steps}] {action} -> {result}")
+            seen_events = len(events)
+
+            status = task.get("status")
+            if status not in ("pending", "running"):
+                result = task.get("result")
+                print(f"\n--- Agent {status}: {result}")
+                return result
+
+            time.sleep(interval)
+
+    def run(self, task: str) -> str | None:
+        """Convenience: execute a task and poll until done."""
+        try:
+            self.execute(task)
+            return self.poll()
+        except KeyboardInterrupt:
+            print("\n\nInterrupted — cancelling task...")
+            self.cancel()
+            return