signal-cli-py 0.2.0__tar.gz

signal_cli_py-0.2.0/.gitignore

@@ -0,0 +1,38 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+*.log
+
+# Config files with real data (never commit)
+signal.json
+*.signal.json
+
+# Test artifacts
+.pytest_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+
+# Local development virtualenv
+.venv/
+venv/
+.venv
+venv
+
+# Editor / IDE
+.idea/
+*.swp
+*.swo
+
+# VS Code - keep useful project settings, ignore user-specific ones
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/tasks.json
+!.vscode/launch.json
+
+# Generated images (if any are committed for docs)
+*.png
+!docs/*.png

signal_cli_py-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 signal-cli-py contributors
+
+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.

signal_cli_py-0.2.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: signal-cli-py
+Version: 0.2.0
+Summary: Reusable Python library and CLI for sending text and images via signal-cli-rest-api. Supports both individuals (phone numbers) and groups.
+Project-URL: Homepage, https://github.com/jower999/signal-cli
+Project-URL: Repository, https://github.com/jower999/signal-cli
+Project-URL: Issues, https://github.com/jower999/signal-cli/issues
+Author: signal-cli maintainers
+License-Expression: MIT
+License-File: LICENSE
+Keywords: delivery,notifications,signal,signal-cli,signal-messaging
+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 :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.32.0
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# signal-cli
+
+A reusable Python library and CLI for sending text messages and images via [signal-cli-rest-api](https://github.com/bbernhard/signal-cli-rest-api).
+
+It supports sending to both **Signal groups** and **individual phone numbers**, and can discover groups your linked account is a member of.
+
+## Installation
+
+```bash
+pip install signal-cli-py
+```
+
+For CLI usage via isolated environment (recommended):
+
+```bash
+pipx install signal-cli-py
+```
+
+> **Note**: After installing, the command is still `signal-cli` (not `signal-cli-py`).  
+> Example: `signal-cli send --recipient team "Hello"`
+> 
+> This is intentional — the PyPI package name is `signal-cli-py` to avoid a naming conflict with an older package.
+
+## Quick Start
+
+### As a Library
+
+```python
+from signal_cli import SignalClient, SignalConfig
+
+# Load from default config (~/.signal-cli/config.json)
+client = SignalClient()
+
+# Send to a saved recipient (group or phone number)
+client.send("Hello from Python", recipient="team-updates")
+
+# Send with an image
+client.send(
+    "Weekly report",
+    recipient="+46700000001",
+    attachments=[{"filename": "report.png", "data": base64_data}]
+)
+
+# Discover live groups from your linked account
+groups = client.list_remote_groups()
+for g in groups:
+    print(g["name"], g["id"])
+```
+
+### As a CLI
+
+```bash
+# Basic setup (stores number + API URL)
+signal-cli setup
+
+# List groups your linked account can see
+signal-cli group-list --available
+
+# Send a message
+signal-cli send --recipient team-updates "Hello team"
+
+# Send with image
+signal-cli send --recipient team-updates --image ./chart.png "Weekly update"
+```
+
+## Configuration
+
+By default, configuration is stored at `~/.signal-cli/config.json`.
+
+You can override the config location in two ways:
+
+```python
+# Explicit path
+cfg = SignalConfig(config_path="/path/to/my-signal.json")
+client = SignalClient(config=cfg)
+
+# Via environment variable
+export SIGNAL_CLI_CONFIG=/path/to/my-signal.json
+```
+
+## Important: Linked Device Behavior
+
+This tool is designed to be used as a **linked device** (not a primary registration).
+
+- New groups created on your phone may not immediately appear when calling `list_remote_groups()` or `group-list --available`.
+- Common triggers that make new groups visible:
+  - Send/receive a message inside the group from your phone
+  - Restart the `signal-cli-rest-api` container
+  - Re-link the device (most reliable)
+
+If a group is missing, the recommended first step is to send a message in it from your phone and then re-check.
+
+## Docker Requirement
+
+Sending requires a running `signal-cli-rest-api` container (usually managed via Docker Compose).
+
+The recommended compose file is installed to `~/.signal-cli/docker-compose.yml` (or you can manage it yourself).
+
+## Development
+
+```bash
+cd signal-cli
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

signal_cli_py-0.2.0/README.md

@@ -0,0 +1,111 @@
+# signal-cli
+
+A reusable Python library and CLI for sending text messages and images via [signal-cli-rest-api](https://github.com/bbernhard/signal-cli-rest-api).
+
+It supports sending to both **Signal groups** and **individual phone numbers**, and can discover groups your linked account is a member of.
+
+## Installation
+
+```bash
+pip install signal-cli-py
+```
+
+For CLI usage via isolated environment (recommended):
+
+```bash
+pipx install signal-cli-py
+```
+
+> **Note**: After installing, the command is still `signal-cli` (not `signal-cli-py`).  
+> Example: `signal-cli send --recipient team "Hello"`
+> 
+> This is intentional — the PyPI package name is `signal-cli-py` to avoid a naming conflict with an older package.
+
+## Quick Start
+
+### As a Library
+
+```python
+from signal_cli import SignalClient, SignalConfig
+
+# Load from default config (~/.signal-cli/config.json)
+client = SignalClient()
+
+# Send to a saved recipient (group or phone number)
+client.send("Hello from Python", recipient="team-updates")
+
+# Send with an image
+client.send(
+    "Weekly report",
+    recipient="+46700000001",
+    attachments=[{"filename": "report.png", "data": base64_data}]
+)
+
+# Discover live groups from your linked account
+groups = client.list_remote_groups()
+for g in groups:
+    print(g["name"], g["id"])
+```
+
+### As a CLI
+
+```bash
+# Basic setup (stores number + API URL)
+signal-cli setup
+
+# List groups your linked account can see
+signal-cli group-list --available
+
+# Send a message
+signal-cli send --recipient team-updates "Hello team"
+
+# Send with image
+signal-cli send --recipient team-updates --image ./chart.png "Weekly update"
+```
+
+## Configuration
+
+By default, configuration is stored at `~/.signal-cli/config.json`.
+
+You can override the config location in two ways:
+
+```python
+# Explicit path
+cfg = SignalConfig(config_path="/path/to/my-signal.json")
+client = SignalClient(config=cfg)
+
+# Via environment variable
+export SIGNAL_CLI_CONFIG=/path/to/my-signal.json
+```
+
+## Important: Linked Device Behavior
+
+This tool is designed to be used as a **linked device** (not a primary registration).
+
+- New groups created on your phone may not immediately appear when calling `list_remote_groups()` or `group-list --available`.
+- Common triggers that make new groups visible:
+  - Send/receive a message inside the group from your phone
+  - Restart the `signal-cli-rest-api` container
+  - Re-link the device (most reliable)
+
+If a group is missing, the recommended first step is to send a message in it from your phone and then re-check.
+
+## Docker Requirement
+
+Sending requires a running `signal-cli-rest-api` container (usually managed via Docker Compose).
+
+The recommended compose file is installed to `~/.signal-cli/docker-compose.yml` (or you can manage it yourself).
+
+## Development
+
+```bash
+cd signal-cli
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

signal_cli_py-0.2.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "signal-cli-py"
+version = "0.2.0"
+description = "Reusable Python library and CLI for sending text and images via signal-cli-rest-api. Supports both individuals (phone numbers) and groups."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "signal-cli maintainers" }
+]
+requires-python = ">=3.10"
+keywords = ["signal", "signal-cli", "signal-messaging", "notifications", "delivery"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "typer[all]>=0.12.0",
+    "requests>=2.32.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "responses>=0.25.0",
+    "ruff>=0.4.0",
+    "black>=24.0",
+]
+
+[project.scripts]
+signal-cli = "signal_cli.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/jower999/signal-cli"
+Repository = "https://github.com/jower999/signal-cli"
+Issues = "https://github.com/jower999/signal-cli/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["signal_cli"]
+include = ["signal_cli/py.typed"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "signal_cli/",
+    "tests/",
+    "README.md",
+    "pyproject.toml",
+]
+exclude = [
+    "**/__pycache__/",
+    "**/*.pyc",
+    ".pytest_cache/",
+    ".vscode/",
+    ".venv/",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"

signal_cli_py-0.2.0/signal_cli/__init__.py

@@ -0,0 +1,10 @@
+from .config import SignalConfig
+from .signal_client import SignalClient
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SignalClient",
+    "SignalConfig",
+    "__version__",
+]

signal_cli_py-0.2.0/signal_cli/cli.py

@@ -0,0 +1,287 @@
+import typer
+import base64
+import json
+import sys
+import webbrowser
+import urllib.parse
+import requests
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import List, Optional
+
+from .config import SignalConfig
+from .signal_client import SignalClient
+
+app = typer.Typer(help="Signal messaging client (send to groups and individuals)")
+
+
+def get_config() -> SignalConfig:
+    return SignalConfig.load()
+
+
+@app.command()
+def setup():
+    """Interactive setup for Signal integration."""
+    config = get_config()
+
+    number = typer.prompt("Your Signal phone number (e.g. +491234567890)")
+    api_url = typer.prompt("signal-cli-rest-api URL", default="http://localhost:8080")
+
+    config.number = number
+    config.api_url = api_url
+    config.save()
+    typer.echo("✅ Basic configuration saved.")
+
+
+@app.command("group-add")
+def group_add(name: str, recipient: str):
+    """Add or update a named recipient (can be a group ID or a phone number)."""
+    config = get_config()
+    config.recipients[name] = recipient
+    config.save()
+    typer.echo(f"✅ Recipient '{name}' saved.")
+
+
+@app.command("group-list")
+def group_list(
+    available: bool = typer.Option(
+        False,
+        "--available",
+        "--remote",
+        help="List groups the linked Signal account is actually a member of (live from the service).",
+    )
+):
+    """List saved named recipients, or live groups from Signal with --available."""
+    config = get_config()
+
+    if available:
+        try:
+            client = SignalClient(config)
+            groups = client.list_remote_groups()
+        except Exception as e:
+            typer.echo(f"Failed to fetch groups from Signal: {e}")
+            raise typer.Exit(1)
+
+        if not groups:
+            typer.echo(
+                "No groups found for this account (or the account is not yet linked)."
+            )
+            return
+
+        typer.echo("\nAvailable groups from your linked Signal account:\n")
+        for i, g in enumerate(groups, 1):
+            gid = g.get("id") or g.get("groupId") or g.get("internal_id", "unknown")
+            name = g.get("name") or g.get("title") or "(no name)"
+            members = g.get("members", [])
+            is_admin = g.get("isAdmin", False)
+            typer.echo(f"  {i}. {name}")
+            typer.echo(f"     ID: {gid}")
+            typer.echo(
+                f"     Members: {len(members)}  |  Admin: {'yes' if is_admin else 'no'}"
+            )
+            typer.echo()
+
+        # Interactive picker to save groups with friendly names
+        if typer.confirm(
+            "Would you like to save any of these groups with a friendly name?",
+            default=False,
+        ):
+            for g in groups:
+                gid = g.get("id") or g.get("groupId") or g.get("internal_id")
+                if not gid:
+                    continue
+                default_name = g.get("name") or g.get("title") or ""
+                if typer.confirm(
+                    f"Save group '{default_name or gid}' ?", default=False
+                ):
+                    friendly = typer.prompt(
+                        "Enter a friendly name for this group", default=default_name
+                    )
+                    if friendly:
+                        config.recipients[friendly] = gid
+                        config.save()
+                        typer.echo(f"✅ Saved as '{friendly}'")
+            typer.echo(
+                "\nDone. Use 'group-list' (without --available) to see your saved names."
+            )
+        return
+
+    # Default: list saved named recipients
+    if not config.recipients:
+        typer.echo(
+            "No recipients configured yet. Use 'group-add <name> <id-or-phone>' or 'group-list --available' to discover groups."
+        )
+        return
+
+    typer.echo("Saved recipients (groups and individuals):\n")
+    for name, rid in config.recipients.items():
+        typer.echo(f"  {name}: {rid}")
+
+
+@app.command("group-remove")
+def group_remove(name: str):
+    """Remove a saved named recipient."""
+    config = get_config()
+    if name in config.recipients:
+        del config.recipients[name]
+        config.save()
+        typer.echo(f"✅ Removed recipient '{name}'")
+    else:
+        typer.echo(f"Recipient '{name}' not found.")
+
+
+@app.command()
+def send(
+    recipient: Optional[str] = typer.Option(
+        None,
+        "--recipient",
+        "-r",
+        help="Recipient name, group ID, or phone number (+467...). Use 'group-list --available' to discover groups.",
+    ),
+    group: Optional[str] = typer.Option(
+        None,
+        "--group",
+        "-g",
+        help="Deprecated alias for --recipient (kept for compatibility with --share).",
+    ),
+    message: Optional[str] = typer.Argument(
+        None, help="Message text (not needed if --json is used)"
+    ),
+    images: Optional[List[Path]] = typer.Option(None, "--image", "-i"),
+    json_input: bool = typer.Option(False, "--json"),
+):
+    """Send a message (with optional images) to a Signal recipient (group or individual)."""
+    config = get_config()
+
+    if not config.number:
+        typer.echo("Please run `signal-cli setup` first.")
+        raise typer.Exit(1)
+
+    # Support both --recipient (new) and --group (legacy alias)
+    target = recipient or group
+
+    attachments = []
+
+    if json_input:
+        data = json.load(sys.stdin)
+        message = data.get("message") or message
+        target = data.get("recipient") or data.get("group") or target
+        attachments = data.get("attachments", [])
+    else:
+        if images:
+            for img_path in images:
+                if str(img_path) in ("-", "/dev/stdin"):
+                    raw = sys.stdin.buffer.read()
+                    if not raw:
+                        typer.echo(
+                            "Error: No image data received on stdin for --image -"
+                        )
+                        raise typer.Exit(1)
+                    b64 = base64.b64encode(raw).decode("utf-8")
+                    attachments.append({"filename": "image.png", "data": b64})
+                elif not img_path.exists():
+                    typer.echo(f"Image not found: {img_path}")
+                    raise typer.Exit(1)
+                else:
+                    with open(img_path, "rb") as f:
+                        data = base64.b64encode(f.read()).decode("utf-8")
+                        attachments.append({"filename": img_path.name, "data": data})
+
+    if not target:
+        typer.echo(
+            "Missing recipient. Use --recipient / -r (or the legacy --group / -g)."
+        )
+        raise typer.Exit(1)
+
+    if not message and not attachments:
+        typer.echo(
+            "Error: MESSAGE is required (or provide attachments via --json or --image)"
+        )
+        raise typer.Exit(1)
+
+    client = SignalClient(config)
+    result = client.send(message, recipient=target, attachments=attachments)
+    typer.echo(f"✅ Message sent. Timestamp: {result.get('timestamp')}")
+
+
+@app.command()
+def link(device_name: str = "signal-cli"):
+    """Generate a linking QR code and open it in your browser."""
+    config = get_config()
+
+    if not config.api_url:
+        typer.echo("No API URL configured. Please run 'signal-cli setup' first.")
+        raise typer.Exit(1)
+
+    url = f"{config.api_url}/v1/qrcodelink?device_name={device_name}"
+
+    try:
+        response = requests.get(url, timeout=15)
+        response.raise_for_status()
+
+        content_type = response.headers.get("Content-Type", "").lower()
+        is_png = "image" in content_type or response.content[:8] == b"\x89PNG\r\n\x1a\n"
+
+        typer.echo("\n✅ Linking QR code generated!")
+
+        if is_png:
+            # Modern behavior of signal-cli-rest-api: the endpoint returns the QR PNG directly
+            png_path = Path(tempfile.gettempdir()) / "signal-cli-link-qr.png"
+            png_path.write_bytes(response.content)
+
+            typer.echo(f"\nQR code saved as PNG: {png_path}")
+            typer.echo("Opening image viewer...")
+
+            try:
+                subprocess.run(["open", str(png_path)], check=False)
+                typer.echo("→ QR code image opened in your default image viewer.")
+            except Exception:
+                typer.echo("→ Could not auto-open the image.")
+                typer.echo(f"   Please open this file manually:\n   {png_path}")
+
+            # We don't have the raw text URI in this case (it's inside the PNG)
+            linking_uri = "(binary PNG QR code returned by API)"
+
+        else:
+            # Older behavior: the endpoint returned the raw tsdevice:/... text URI
+            linking_uri = response.text.strip()
+
+            typer.echo(f"\nLinking URI:\n{linking_uri}\n")
+
+            # URL-encode and let quickchart turn it into a QR image
+            encoded_uri = urllib.parse.quote(linking_uri, safe="")
+            qr_url = f"https://quickchart.io/qr?text={encoded_uri}&size=300"
+
+            try:
+                webbrowser.open(qr_url)
+                typer.echo("→ A QR code has been opened in your browser.")
+            except Exception:
+                typer.echo("→ Could not open browser automatically.")
+                typer.echo(
+                    f"   Open this link manually to see the QR code:\n   {qr_url}"
+                )
+
+        typer.echo("\nNext steps:")
+        typer.echo("1. Open the Signal app on your **phone**")
+        typer.echo("2. Go to Profile → Linked Devices → 'Link New Device'")
+        typer.echo("3. Scan the QR code")
+        typer.echo("\nAfter scanning, wait 10–20 seconds, then run:")
+        typer.echo("  signal-cli status")
+
+    except requests.exceptions.RequestException as e:
+        typer.echo(f"Failed to generate linking URI: {e}")
+        typer.echo(
+            "Make sure the signal-cli-rest-api is running on the configured URL."
+        )
+        typer.echo(
+            "If you see 'UnsupportedOperationException', edit docker-compose.signal.yml"
+        )
+        typer.echo(
+            "to use MODE=native (or normal) instead of json-rpc, then restart the container."
+        )
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

signal_cli_py-0.2.0/signal_cli/config.py

@@ -0,0 +1,145 @@
+from pathlib import Path
+import json
+import os
+import warnings
+from typing import Dict, Optional, Union
+
+# Default configuration directory for standalone use.
+DEFAULT_CONFIG_DIR = Path.home() / ".signal-cli"
+DEFAULT_CONFIG_FILE = DEFAULT_CONFIG_DIR / "config.json"
+
+
+class SignalConfig:
+    """
+    Configuration for the Signal delivery client.
+
+    Supports:
+    - Custom config file location (constructor or SIGNAL_CLI_CONFIG env var)
+    - Backward compatibility with very old config files that used "groups" instead of "recipients"
+    - Named shortcuts that can point to either Signal groups or individual phone numbers
+    """
+
+    def __init__(self, config_path: Optional[Union[str, Path]] = None):
+        self._config_path = self._resolve_config_path(config_path)
+
+        self.number: Optional[str] = None
+        self.api_url: str = "http://localhost:8080"
+
+        # Canonical storage (new name)
+        self.recipients: Dict[str, str] = {}
+
+        # Legacy compatibility shim (see @property below)
+        self._migrated_from_groups = False
+
+    # --------------------------------------------------------------------- #
+    # Path resolution
+    # --------------------------------------------------------------------- #
+    def _resolve_config_path(self, explicit: Optional[Union[str, Path]]) -> Path:
+        if explicit:
+            return Path(explicit).expanduser()
+        env = os.environ.get("SIGNAL_CLI_CONFIG")
+        if env:
+            return Path(env).expanduser()
+        return DEFAULT_CONFIG_FILE
+
+    @property
+    def config_path(self) -> Path:
+        """The actual path this config instance will read from / write to."""
+        return self._config_path
+
+    # --------------------------------------------------------------------- #
+    # Legacy "groups" compatibility shim
+    # --------------------------------------------------------------------- #
+    @property
+    def groups(self) -> Dict[str, str]:
+        """Backward-compat alias. Prefer .recipients in new code."""
+        warnings.warn(
+            "SignalConfig.groups is deprecated and will be removed in 0.3.0. "
+            "Use .recipients instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.recipients
+
+    @groups.setter
+    def groups(self, value: Dict[str, str]):
+        warnings.warn(
+            "SignalConfig.groups is deprecated and will be removed in 0.3.0. "
+            "Use .recipients instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.recipients = value
+
+    # --------------------------------------------------------------------- #
+    # Persistence
+    # --------------------------------------------------------------------- #
+    @classmethod
+    def load(cls, config_path: Optional[Union[str, Path]] = None) -> "SignalConfig":
+        config = cls(config_path=config_path)
+        path = config._config_path
+
+        if not path.exists():
+            return config
+
+        try:
+            data = json.loads(path.read_text())
+        except Exception:
+            # Corrupt file — start fresh but keep the path
+            return config
+
+        config.number = data.get("number")
+        config.api_url = data.get("api_url", config.api_url)
+
+        # New key takes precedence
+        if "recipients" in data:
+            config.recipients = data.get("recipients", {}) or {}
+        elif "groups" in data:
+            # One-time migration from legacy "groups" key (very old config files)
+            config.recipients = data.get("groups", {}) or {}
+            config._migrated_from_groups = True
+
+        # Auto-clean the file on first migration so users don't keep the old key forever
+        if config._migrated_from_groups:
+            try:
+                config.save()
+            except Exception:
+                pass  # non-fatal
+
+        return config
+
+    def save(self) -> None:
+        """Persist configuration. Always writes under the modern 'recipients' key."""
+        self._config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        data: Dict[str, object] = {
+            "number": self.number,
+            "api_url": self.api_url,
+            "recipients": self.recipients,
+        }
+
+        # If we migrated on this run, we already dropped the old key by not writing it.
+        self._config_path.write_text(json.dumps(data, indent=2))
+
+    # --------------------------------------------------------------------- #
+    # Resolution helpers
+    # --------------------------------------------------------------------- #
+    def resolve_recipient(self, name_or_id: str) -> str:
+        """
+        Resolve a friendly name (or raw ID/phone) to the actual Signal recipient.
+
+        Works for both saved group IDs and saved individual phone numbers.
+        If the value is not a known name, it is returned as-is (assumed to be
+        a raw group ID or phone number).
+        """
+        return self.recipients.get(name_or_id, name_or_id)
+
+    # Keep old name working during the transition period (used by SignalClient today)
+    def get_group_id(self, name_or_id: str) -> str:
+        """Deprecated alias for resolve_recipient. Will be removed in 0.3.0."""
+        warnings.warn(
+            "get_group_id() is deprecated, use resolve_recipient() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.resolve_recipient(name_or_id)

signal_cli_py-0.2.0/signal_cli/py.typed

@@ -0,0 +1 @@
+# This file marks the package as supporting type checking (PEP 561)

signal_cli_py-0.2.0/signal_cli/signal_client.py

@@ -0,0 +1,151 @@
+import mimetypes
+import warnings
+from typing import List, Dict, Optional
+
+import requests
+
+from .config import SignalConfig
+
+
+class SignalClient:
+    """
+    Client for sending messages and attachments via signal-cli-rest-api.
+
+    Can be used either with a SignalConfig or with direct credentials.
+    Standalone usage with explicit number/api_url is fully supported.
+    """
+
+    def __init__(
+        self,
+        config: Optional[SignalConfig] = None,
+        number: Optional[str] = None,
+        api_url: Optional[str] = None,
+    ):
+        """
+        Create a SignalClient.
+
+        Args:
+            config: A SignalConfig instance (provides number, api_url, and named recipients).
+            number: Override the sending phone number (E.164 format).
+            api_url: Override the signal-cli-rest-api base URL.
+        """
+        if config is None:
+            config = SignalConfig()
+
+        self.config = config
+        self._number = number or config.number
+        self._api_url = api_url or config.api_url
+
+    @property
+    def number(self) -> Optional[str]:
+        return self._number
+
+    @property
+    def api_url(self) -> str:
+        return self._api_url
+
+    # ------------------------------------------------------------------ #
+    # Core sending
+    # ------------------------------------------------------------------ #
+    def send(
+        self,
+        message: str,
+        recipient: Optional[str] = None,
+        attachments: Optional[List[Dict[str, str]]] = None,
+        *,
+        # Deprecated alias kept for backward compatibility during transition
+        group: Optional[str] = None,
+    ) -> dict:
+        """
+        Send a text message (optionally with attachments) to a recipient.
+
+        The recipient can be:
+        - A friendly name saved in config.recipients
+        - A raw Signal group ID (group.XXXX...)
+        - A phone number in E.164 format (+467...)
+
+        Args:
+            message: Text to send.
+            recipient: Target (name, group ID, or phone number). Preferred parameter.
+            attachments: Optional list of {"filename": , "data": base64} dicts.
+            group: Deprecated alias for recipient. Will be removed in 0.3.0.
+        """
+        if group is not None:
+            if recipient is None:
+                recipient = group
+            else:
+                raise ValueError("Specify either 'recipient' or 'group', not both.")
+            warnings.warn(
+                "The 'group' parameter is deprecated. Use 'recipient' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        if not recipient:
+            raise ValueError("recipient is required")
+
+        recipient_id = self.config.resolve_recipient(recipient)
+
+        if not self.number:
+            raise RuntimeError(
+                "No sending phone number configured. "
+                "Run `signal-cli setup` or pass number= to SignalClient()."
+            )
+
+        payload: Dict[str, object] = {
+            "number": self.number,
+            "message": message,
+            "recipients": [recipient_id],
+        }
+
+        if attachments:
+            payload["base64_attachments"] = [
+                self._format_attachment(att) for att in attachments
+            ]
+
+        response = requests.post(
+            f"{self.api_url}/v2/send",
+            json=payload,
+            timeout=60,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    # ------------------------------------------------------------------ #
+    # Group discovery (powers `group list --available`)
+    # ------------------------------------------------------------------ #
+    def list_remote_groups(self) -> List[dict]:
+        """
+        Fetch the list of Signal groups the linked account is a member of.
+
+        This calls the signal-cli-rest-api endpoint:
+            GET /v1/groups/{number}
+
+        Returns the raw list of group objects (containing id, name, members, etc.).
+        """
+        if not self.number:
+            raise RuntimeError(
+                "Cannot list groups: no phone number is configured on this client."
+            )
+
+        url = f"{self.api_url}/v1/groups/{self.number}"
+        resp = requests.get(url, timeout=30)
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _format_attachment(attachment: Dict[str, str]) -> str:
+        data = attachment["data"]
+        if data.startswith("data:"):
+            return data
+
+        filename = attachment.get("filename", "attachment.bin")
+        mime_type = (
+            attachment.get("content_type")
+            or mimetypes.guess_type(filename)[0]
+            or "application/octet-stream"
+        )
+        return f"data:{mime_type};filename={filename};base64,{data}"

signal_cli_py-0.2.0/tests/__init__.py

@@ -0,0 +1 @@
+# Tests for the signal-cli package

signal_cli_py-0.2.0/tests/conftest.py

@@ -0,0 +1,30 @@
+import tempfile
+from pathlib import Path
+import pytest
+
+
+@pytest.fixture
+def temp_config_path():
+    """Provide a temporary config file path for isolated tests."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        path = Path(tmpdir) / "test-signal.json"
+        yield path
+
+
+@pytest.fixture
+def config_with_legacy_groups(temp_config_path):
+    """Create a SignalConfig file that still uses the old 'groups' key (for migration testing)."""
+    data = {
+        "number": "+46700000001",
+        "api_url": "http://localhost:8080",
+        "groups": {
+            "team": "group.ABC123",
+            "boss": "+46700000002",
+        },
+    }
+    temp_config_path.write_text(str(data).replace("'", '"'))  # simple json-like
+    # Better to write proper JSON
+    import json
+
+    temp_config_path.write_text(json.dumps(data, indent=2))
+    return temp_config_path

signal_cli_py-0.2.0/tests/test_client.py

@@ -0,0 +1,64 @@
+import responses
+
+from signal_cli.config import SignalConfig
+from signal_cli.signal_client import SignalClient
+
+
+@responses.activate
+def test_list_remote_groups_returns_data():
+    """SignalClient.list_remote_groups should call the correct endpoint and return the response."""
+    number = "+46700000001"  # single source of truth for test data
+
+    cfg = SignalConfig()
+    cfg.number = number
+    cfg.api_url = "http://localhost:8080"
+
+    mock_response = [
+        {"id": "group.ABC", "name": "Team A", "members": ["+1", "+2"]},
+        {"id": "group.DEF", "name": "Team B", "members": ["+3"]},
+    ]
+
+    responses.add(
+        responses.GET,
+        f"http://localhost:8080/v1/groups/{number}",
+        json=mock_response,
+        status=200,
+    )
+
+    client = SignalClient(config=cfg)
+    groups = client.list_remote_groups()
+
+    assert len(groups) == 2
+    assert groups[0]["name"] == "Team A"
+    assert responses.calls[0].request.url.endswith(f"/v1/groups/{number}")
+
+
+@responses.activate
+def test_send_uses_recipient():
+    """SignalClient.send should resolve the recipient and call /v2/send with correct payload."""
+    cfg = SignalConfig()
+    cfg.number = "+46700000001"
+    cfg.api_url = "http://localhost:8080"
+    cfg.recipients["team"] = "group.XYZ123"
+
+    responses.add(
+        responses.POST,
+        "http://localhost:8080/v2/send",
+        json={"timestamp": 123456789},
+        status=200,
+    )
+
+    client = SignalClient(config=cfg)
+    result = client.send("Hello team", recipient="team")
+
+    assert result["timestamp"] == 123456789
+
+    request = responses.calls[0].request
+    payload = (
+        request.body.decode()
+        if isinstance(request.body, (bytes, bytearray))
+        else request.body
+    )
+
+    assert "group.XYZ123" in payload  # the resolved recipient
+    assert "Hello team" in payload

signal_cli_py-0.2.0/tests/test_config.py

@@ -0,0 +1,39 @@
+import json
+
+from signal_cli.config import SignalConfig
+
+
+def test_load_with_legacy_groups_migrates_to_recipients(config_with_legacy_groups):
+    """Loading a config that still has the old 'groups' key should migrate to 'recipients'."""
+    cfg = SignalConfig.load(config_with_legacy_groups)
+
+    assert "team" in cfg.recipients
+    assert cfg.recipients["team"] == "group.ABC123"
+    assert "boss" in cfg.recipients
+
+    # After load + save, the file should no longer contain the old key
+    data = json.loads(config_with_legacy_groups.read_text())
+    assert "recipients" in data
+    assert "groups" not in data
+
+
+def test_custom_config_path(temp_config_path):
+    """SignalConfig should respect an explicit config_path."""
+    cfg = SignalConfig(config_path=temp_config_path)
+    cfg.number = "+123456"
+    cfg.recipients["test"] = "group.TEST"
+    cfg.save()
+
+    assert temp_config_path.exists()
+
+    # Load it back
+    cfg2 = SignalConfig.load(temp_config_path)
+    assert cfg2.number == "+123456"
+    assert cfg2.recipients["test"] == "group.TEST"
+
+
+def test_load_nonexistent_path_returns_empty_config(temp_config_path):
+    """Loading a path that does not exist should return a default config."""
+    cfg = SignalConfig.load(temp_config_path)
+    assert cfg.number is None
+    assert cfg.recipients == {}