chatwire 0.2.0__tar.gz

chatwire-0.2.0/LICENSE

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

chatwire-0.2.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: chatwire
+Version: 0.2.0
+Summary: macOS chat-relay bridge: iMessage <-> Telegram, web UI, and pluggable integrations
+Author: Allen Bina
+License: MIT License
+        
+        Copyright (c) 2026 Allen Bina
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/allenbina/chatwire
+Project-URL: Issues, https://github.com/allenbina/chatwire/issues
+Keywords: imessage,telegram,macos,bridge,relay
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-telegram-bot<22,>=21.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pywebpush>=2.0
+Requires-Dist: httpx
+Requires-Dist: jsonschema>=4
+Dynamic: license-file
+
+# chatwire
+
+Relay iMessages from a macOS host to other places — currently a Telegram bot
+and a web UI, with more integrations planned.
+
+> Originally branded `chat-bridge`; renamed to `chatwire` for v0.2.0 because
+> PyPI's similarity check rejected `chat-bridge` (collides with an unrelated
+> `chatbridge` package).
+
+> **Status:** alpha. The author runs this daily; nobody else has installed it
+> yet. Things will change. See [`docs/OPEN_SOURCE_PLAN.md`](docs/OPEN_SOURCE_PLAN.md)
+> for the roadmap.
+
+## What it does
+
+- **Inbound.** A small Python service polls `~/Library/Messages/chat.db`,
+  resolves senders against Contacts.app, and forwards messages (text, photos,
+  videos, attachments) to your configured integrations.
+- **Outbound.** Reply from your phone, your laptop, anywhere — the service
+  drives Messages.app via AppleScript to send back as you.
+- **Group chats.** First-class. Replies route by chat GUID, not the sender's
+  1:1 handle, so you can keep a group conversation in Telegram or the web UI
+  and replies land back in the group.
+
+## Constraints
+
+iMessage is Mac-only. The bridge has to live on a Mac with the user's Apple
+ID logged into Messages.app, granted Full Disk Access (to read `chat.db`)
+and Automation→Messages (to send). macOS gates both behind System Settings
+clicks that no installer can bypass — the setup wizard makes them as short
+as possible, but you will click through some prompts the first time.
+
+Tested on macOS 12 Monterey. macOS 13–15 should work; not yet smoke-tested.
+See `docs/OPEN_SOURCE_PLAN.md` for the support matrix.
+
+## Install
+
+Recommended path: **pipx**, against python.org's Python.
+
+```bash
+# Install python.org Python first if you don't have it:
+#   https://www.python.org/downloads/macos/
+# (Homebrew Python works but TCC treats it as a different identity —
+# you'd have to grant Full Disk Access + Automation to that binary
+# specifically. python.org is the well-trodden path.)
+
+# Install pipx if you don't have it (once per machine):
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+
+# Install chatwire (from PyPI, once v0.2.0 ships):
+pipx install --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 \
+    chatwire
+
+# Or from the v0.1.0 git tag (still under the old chat-bridge repo URL —
+# the GitHub redirect to chatwire keeps this working):
+pipx install --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 \
+    git+https://github.com/allenbina/chatwire.git@v0.1.0
+
+# Wire it up:
+chatwire install-agents
+chatwire setup
+```
+
+The setup wizard walks you through the Telegram bot token, the macOS
+permission grants (Full Disk Access + Automation→Messages), and writes
+`~/.chatwire/config.json`.
+
+### Alternate install methods
+
+**Homebrew tap.** Convenient if you already use brew. Note: the formula
+still ships under the old `chat-bridge` name in the tap; renaming the
+formula is tracked separately.
+
+```bash
+brew install allenbina/tap/chat-bridge
+chatwire install-agents
+chatwire setup
+```
+
+Tap source: <https://github.com/allenbina/homebrew-tap>.
+
+**curl-pipe-bash.** No PyPI access, no Homebrew, just a shell.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/allenbina/chatwire/main/scripts/install.sh | bash
+```
+
+Pin to a tag with `CHATWIRE_REF=v0.1.0`. The script refuses Xcode CLT's
+Python stub and warns on Homebrew Python (TCC identity protection). Same
+post-install steps (`chatwire install-agents` etc.).
+
+**Developer / git-clone path.** For hacking on the bridge itself:
+
+```bash
+git clone https://github.com/allenbina/chatwire.git ~/projects/chatwire
+cd ~/projects/chatwire
+python3 -m venv .venv
+.venv/bin/pip install -e .
+
+# Render and load the launchd agents:
+.venv/bin/chatwire install-agents
+
+# (legacy installs only) one-shot migration from ~/.imessage-tg/.env:
+.venv/bin/chatwire migrate
+
+# Sanity check:
+.venv/bin/chatwire doctor
+```
+
+Configure `~/.chatwire/config.json` (chmod 600). Schema:
+
+```json
+{
+  "version": 1,
+  "TELEGRAM_BOT_TOKEN": "...",
+  "TELEGRAM_ALLOWED_USER_IDS": "123456789",
+  "SELF_HANDLES": "+1XXXXXXXXXX,you@icloud.com",
+  "WEB_PORT": "8723"
+}
+```
+
+The setup wizard (Phase 2) will write this for you. Until then it's hand-edited.
+
+## macOS permissions
+
+Both the FDA grant and the Automation→Messages grant need to be given to the
+**python.org Python binary** (not Homebrew's), because the python.org
+installer ships two Mach-O binaries with different code-signing identities
+that TCC tracks separately. See
+[`docs/REFERENCE_INSTALL.md`](docs/REFERENCE_INSTALL.md) section 5 for the
+full walkthrough — that section was the reason the bridge worked at all on
+the first install, and it's the same on every Mac.
+
+`scripts/check-permissions.sh` (or `chatwire doctor`) will tell you
+which prompts you still need to click.
+
+## Repo layout
+
+```
+bridge.py             telegram bot + outbound (TG -> iMessage)
+chat_db.py            reads chat.db, HEIC -> JPEG via sips
+chat_send.py          osascript wrappers (send_text, send_file)
+prefix.py             message prefix formatter + reply parser
+config.py             config.json loader (with .env fallback)
+chatwire_cli.py       setup / install-agents / logs / doctor / migrate
+contacts.py           Contacts.app -> handle/name lookup
+echo_log.py           cross-process echo dedup
+whitelist.py          runtime-mutable allowlist
+_version.py           release-semver source of truth
+web/                  FastAPI web UI + first-run setup wizard
+migrations/           config-schema migration runner
+templates/launchd/    plist templates rendered by install-agents
+scripts/install.sh    curl-pipe-bash installer (alternative to brew)
+docs/                 OPEN_SOURCE_PLAN.md, REFERENCE_INSTALL.md
+```
+
+## Trademarks
+
+iMessage, Messages, macOS, and AppleScript are trademarks of Apple Inc.,
+referenced here in their descriptive sense — this project relays to and
+from Apple's iMessage service. **chatwire is not affiliated with,
+endorsed by, or sponsored by Apple Inc.**
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Contributing
+
+Not accepting PRs yet — Phase 1 is mid-flight. Open an issue if you have
+questions or hit a wall installing.

chatwire-0.2.0/README.md

@@ -0,0 +1,172 @@
+# chatwire
+
+Relay iMessages from a macOS host to other places — currently a Telegram bot
+and a web UI, with more integrations planned.
+
+> Originally branded `chat-bridge`; renamed to `chatwire` for v0.2.0 because
+> PyPI's similarity check rejected `chat-bridge` (collides with an unrelated
+> `chatbridge` package).
+
+> **Status:** alpha. The author runs this daily; nobody else has installed it
+> yet. Things will change. See [`docs/OPEN_SOURCE_PLAN.md`](docs/OPEN_SOURCE_PLAN.md)
+> for the roadmap.
+
+## What it does
+
+- **Inbound.** A small Python service polls `~/Library/Messages/chat.db`,
+  resolves senders against Contacts.app, and forwards messages (text, photos,
+  videos, attachments) to your configured integrations.
+- **Outbound.** Reply from your phone, your laptop, anywhere — the service
+  drives Messages.app via AppleScript to send back as you.
+- **Group chats.** First-class. Replies route by chat GUID, not the sender's
+  1:1 handle, so you can keep a group conversation in Telegram or the web UI
+  and replies land back in the group.
+
+## Constraints
+
+iMessage is Mac-only. The bridge has to live on a Mac with the user's Apple
+ID logged into Messages.app, granted Full Disk Access (to read `chat.db`)
+and Automation→Messages (to send). macOS gates both behind System Settings
+clicks that no installer can bypass — the setup wizard makes them as short
+as possible, but you will click through some prompts the first time.
+
+Tested on macOS 12 Monterey. macOS 13–15 should work; not yet smoke-tested.
+See `docs/OPEN_SOURCE_PLAN.md` for the support matrix.
+
+## Install
+
+Recommended path: **pipx**, against python.org's Python.
+
+```bash
+# Install python.org Python first if you don't have it:
+#   https://www.python.org/downloads/macos/
+# (Homebrew Python works but TCC treats it as a different identity —
+# you'd have to grant Full Disk Access + Automation to that binary
+# specifically. python.org is the well-trodden path.)
+
+# Install pipx if you don't have it (once per machine):
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+
+# Install chatwire (from PyPI, once v0.2.0 ships):
+pipx install --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 \
+    chatwire
+
+# Or from the v0.1.0 git tag (still under the old chat-bridge repo URL —
+# the GitHub redirect to chatwire keeps this working):
+pipx install --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 \
+    git+https://github.com/allenbina/chatwire.git@v0.1.0
+
+# Wire it up:
+chatwire install-agents
+chatwire setup
+```
+
+The setup wizard walks you through the Telegram bot token, the macOS
+permission grants (Full Disk Access + Automation→Messages), and writes
+`~/.chatwire/config.json`.
+
+### Alternate install methods
+
+**Homebrew tap.** Convenient if you already use brew. Note: the formula
+still ships under the old `chat-bridge` name in the tap; renaming the
+formula is tracked separately.
+
+```bash
+brew install allenbina/tap/chat-bridge
+chatwire install-agents
+chatwire setup
+```
+
+Tap source: <https://github.com/allenbina/homebrew-tap>.
+
+**curl-pipe-bash.** No PyPI access, no Homebrew, just a shell.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/allenbina/chatwire/main/scripts/install.sh | bash
+```
+
+Pin to a tag with `CHATWIRE_REF=v0.1.0`. The script refuses Xcode CLT's
+Python stub and warns on Homebrew Python (TCC identity protection). Same
+post-install steps (`chatwire install-agents` etc.).
+
+**Developer / git-clone path.** For hacking on the bridge itself:
+
+```bash
+git clone https://github.com/allenbina/chatwire.git ~/projects/chatwire
+cd ~/projects/chatwire
+python3 -m venv .venv
+.venv/bin/pip install -e .
+
+# Render and load the launchd agents:
+.venv/bin/chatwire install-agents
+
+# (legacy installs only) one-shot migration from ~/.imessage-tg/.env:
+.venv/bin/chatwire migrate
+
+# Sanity check:
+.venv/bin/chatwire doctor
+```
+
+Configure `~/.chatwire/config.json` (chmod 600). Schema:
+
+```json
+{
+  "version": 1,
+  "TELEGRAM_BOT_TOKEN": "...",
+  "TELEGRAM_ALLOWED_USER_IDS": "123456789",
+  "SELF_HANDLES": "+1XXXXXXXXXX,you@icloud.com",
+  "WEB_PORT": "8723"
+}
+```
+
+The setup wizard (Phase 2) will write this for you. Until then it's hand-edited.
+
+## macOS permissions
+
+Both the FDA grant and the Automation→Messages grant need to be given to the
+**python.org Python binary** (not Homebrew's), because the python.org
+installer ships two Mach-O binaries with different code-signing identities
+that TCC tracks separately. See
+[`docs/REFERENCE_INSTALL.md`](docs/REFERENCE_INSTALL.md) section 5 for the
+full walkthrough — that section was the reason the bridge worked at all on
+the first install, and it's the same on every Mac.
+
+`scripts/check-permissions.sh` (or `chatwire doctor`) will tell you
+which prompts you still need to click.
+
+## Repo layout
+
+```
+bridge.py             telegram bot + outbound (TG -> iMessage)
+chat_db.py            reads chat.db, HEIC -> JPEG via sips
+chat_send.py          osascript wrappers (send_text, send_file)
+prefix.py             message prefix formatter + reply parser
+config.py             config.json loader (with .env fallback)
+chatwire_cli.py       setup / install-agents / logs / doctor / migrate
+contacts.py           Contacts.app -> handle/name lookup
+echo_log.py           cross-process echo dedup
+whitelist.py          runtime-mutable allowlist
+_version.py           release-semver source of truth
+web/                  FastAPI web UI + first-run setup wizard
+migrations/           config-schema migration runner
+templates/launchd/    plist templates rendered by install-agents
+scripts/install.sh    curl-pipe-bash installer (alternative to brew)
+docs/                 OPEN_SOURCE_PLAN.md, REFERENCE_INSTALL.md
+```
+
+## Trademarks
+
+iMessage, Messages, macOS, and AppleScript are trademarks of Apple Inc.,
+referenced here in their descriptive sense — this project relays to and
+from Apple's iMessage service. **chatwire is not affiliated with,
+endorsed by, or sponsored by Apple Inc.**
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Contributing
+
+Not accepting PRs yet — Phase 1 is mid-flight. Open an issue if you have
+questions or hit a wall installing.

chatwire-0.2.0/_version.py

@@ -0,0 +1,12 @@
+"""Single source of truth for the bridge release version.
+
+Bumped at release time. Used by:
+  - web/main.py for /healthz and the update-check banner
+  - chatwire_cli.py for `--version`
+  - pyproject.toml dynamic version
+
+Format: PEP 440-flavored semver. Pre-1.0 dev builds carry a `-dev` suffix
+which the update-check JS treats as "skip the check" (no point pinging
+GitHub when you cloned from main).
+"""
+__version__ = "0.2.0"