Concise README with a screenshot (Signal vibes, made-up data)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,110 +1,20 @@
|
|||||||
# bubble
|
# bubble
|
||||||
|
|
||||||
A Signal Desktop–style SMS client for [voip.ms](https://voip.ms). It keeps your full message history on your own machine, lets you search it, and shows your GNOME contacts' names and photos.
|

|
||||||
|
|
||||||
## Features
|
A Signal-style desktop SMS/MMS client for [voip.ms](https://voip.ms) and Google Voice (Electron, Linux), plus a companion texting app for the Rabbit R1 (`android/`).
|
||||||
|
|
||||||
- A conversation list on the left, with contact photos, previews, times, and unread badges. The chat opens on the right.
|
- Keeps your whole message history locally (SQLite), with full-text search
|
||||||
- A **full local copy of your history.** On first run the app imports everything from voip.ms, working backwards in 90-day windows, and picks up where it left off if interrupted. After that it checks for new messages every 30 seconds (you can change this).
|
- Group chats, MMS, reactions, emoji shortcodes, GNOME contacts
|
||||||
- **Search** everything from the sidebar (Ctrl+F). Results show a highlighted preview, and clicking one jumps to that exact message. You can also search inside a single chat (Ctrl+Shift+F), using Enter and Shift+Enter to step through the matches.
|
- Optional end-to-end-sealed relay to sync with the Rabbit R1 (`server/`)
|
||||||
- **New chat** (Ctrl+N), with autocomplete from your contacts by name or number.
|
|
||||||
- Contacts are read-only, straight from GNOME's Evolution Data Server caches: your Nextcloud CardDAV books and anything else GNOME Contacts shows. They reload automatically when the books sync.
|
|
||||||
- Messages longer than 160 characters are split automatically. If a send fails, it's marked with Retry and Delete options.
|
|
||||||
- **MMS**: photos, video and audio appear inline in the chat. Click a photo to view it full size or save it. You can attach up to 3 files with the paperclip, by drag-and-drop, or by pasting. Photos too big for voip.ms (the budget is 900 KB each) are shrunk automatically before sending.
|
|
||||||
- **Emoji shortcodes**: type `:` and at least two letters, for example `:jo`, to get matching emoji. Pick one with ↑/↓ and Tab/Enter or by clicking it; Esc closes the list. A finished `:joy:` converts on its own. The shortcodes are Signal's and Slack's, from [emoji-datasource](https://github.com/iamcal/emoji-data); `npm run gen:emoji` regenerates them.
|
|
||||||
- Alt+↑/↓ moves between conversations.
|
|
||||||
- Ctrl +/− zooms and Ctrl 0 resets. Choose Light, Dark, or System under Settings → Appearance, and the dark or inverted (lighter) icon.
|
|
||||||
- **The Rabbit's SIM, from here** (Settings → Rabbit relay): with bubble as the Rabbit R1's texting app, its SIM is a third number to text from ("Rabbit SIM"), its texts show up here, and chat names and read/unread/archived stay in step with the Rabbit, no cable needed. It goes through a small relay on jai (`server/bubble_relay.py`, deployed with `scripts/deploy-jai.sh`), which only ever holds AES-256-GCM-sealed messages: the key lives on this computer and the Rabbit, never on jai. A text sent from here goes out at the Rabbit's next background check, so it can take a while; older photos come over when you open them.
|
|
||||||
|
|
||||||
## Where your data lives
|
## Run
|
||||||
|
|
||||||
| What | Where | Backed up? |
|
|
||||||
|---|---|---|
|
|
||||||
| Message database | `~/Documents/bubble-data/messages.db` | ✅ Déjà Dup covers `~/Documents` |
|
|
||||||
| Daily snapshots, last 7 kept | `~/Documents/bubble-data/snapshots/` | ✅ |
|
|
||||||
| Settings | `~/Documents/bubble-data/settings.json` | ✅ |
|
|
||||||
| MMS photos and attachments (cached on arrival) | `~/Documents/bubble-data/media/` | ✅ |
|
|
||||||
| API password | GNOME Keyring (via Electron `safeStorage`) → `~/.config/voipms-desktop/credentials.bin` | ❌ on purpose; you re-enter it after a restore |
|
|
||||||
| Contact photo cache | `~/.config/voipms-desktop/photo-cache/` | ❌ not needed |
|
|
||||||
| Rabbit relay address, token and key | GNOME Keyring → `~/.config/voip.ms Messages/relay.bin` | ❌ on purpose; reconnect and Sync to Rabbit after a restore |
|
|
||||||
|
|
||||||
The snapshots are consistent SQLite copies, made daily and whenever you quit. So even if a backup catches the live database halfway through a write, the backup still holds a clean, restorable copy. To move the data folder, go to Settings → Storage → Move…. If you point it at a folder that already holds a `messages.db`, for example one restored from backup, the app uses that history.
|
|
||||||
|
|
||||||
## Setup
|
|
||||||
|
|
||||||
In the voip.ms portal, go to **Main Menu → SOAP & REST/JSON API** and:
|
|
||||||
|
|
||||||
1. Enable the API.
|
|
||||||
2. Set an **API password**. This is separate from your login password.
|
|
||||||
3. Add your IP address under **Enable IP Addresses**.
|
|
||||||
|
|
||||||
Then launch the app and enter your account email and API password.
|
|
||||||
|
|
||||||
### The Rabbit relay (optional)
|
|
||||||
|
|
||||||
1. `scripts/deploy-jai.sh` puts the relay on jai (its own folder, port 8080 on the tailscale address only); `scripts/deploy-jai.sh --token` prints its token.
|
|
||||||
2. Settings → Rabbit relay: paste the token, Connect.
|
|
||||||
3. Plug in the Rabbit and press Sync to Rabbit once: that hands it the address, token and the sealing key.
|
|
||||||
|
|
||||||
### Apple-style emoji (optional)
|
|
||||||
|
|
||||||
To look like Signal, the app uses an `Apple Color Emoji` font when one is installed, and falls back to Noto Color Emoji otherwise. To install it for your user only (about 116 MB):
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
curl -L -o ~/.local/share/fonts/AppleColorEmoji.ttf \
|
npm run deps:install # via sfw (npm i -g sfw)
|
||||||
https://github.com/samuelngs/apple-emoji-linux/releases/latest/download/AppleColorEmoji-Linux.ttf
|
VOIPMS_SANDBOX=/tmp/bubble-demo npm run dev # try it with made-up data
|
||||||
fc-cache -f
|
npm run dev # real account: enter your voip.ms API login
|
||||||
|
npm run install-desktop # build the AppImage + GNOME launcher
|
||||||
```
|
```
|
||||||
|
|
||||||
Alternatively, install the `fonts-apple-color-emoji.rpm` from the same release to make it available system-wide. Restart the app afterward.
|
voip.ms setup: Main Menu → SOAP & REST/JSON API → enable the API, set an API password, allow your IP.
|
||||||
|
|
||||||
## Development
|
|
||||||
|
|
||||||
Dependencies are installed through [Socket Firewall](https://docs.socket.dev/docs/socket-firewall-free)
|
|
||||||
(`sfw`), which checks every package, transitive ones included, against socket.dev
|
|
||||||
before npm downloads it. Install it once with `npm i -g sfw`, then use the
|
|
||||||
`deps:*` scripts instead of bare `npm install` (a Claude Code hook in
|
|
||||||
`.claude/` enforces this for Claude):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run deps:install # after cloning or pulling changes to package-lock.json
|
|
||||||
npm run deps:add -- pkg # add a package
|
|
||||||
npm run deps:update # update within package.json's ranges
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run dev # run with hot reload
|
|
||||||
npm test # unit tests (run under Electron's Node for better-sqlite3)
|
|
||||||
npm run test:live # also reads your real EDS address books (read-only)
|
|
||||||
npm run typecheck
|
|
||||||
npm run install-desktop # build the AppImage and add a GNOME launcher
|
|
||||||
```
|
|
||||||
|
|
||||||
To try the app or work on the UI without going near your real account, run it
|
|
||||||
in a sandbox. Everything it uses (Electron profile, so no saved voip.ms password
|
|
||||||
or Google sign-in, plus settings and the message database) lives under the given
|
|
||||||
folder; it skips your address book and fills itself with made-up conversations,
|
|
||||||
1:1 and group, on a demo voip.ms number and a demo Google Voice number:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
VOIPMS_SANDBOX=/tmp/voipms-sandbox npm run dev # or VOIPMS_DEMO=1, same folder
|
|
||||||
rm -rf /tmp/voipms-sandbox # start over
|
|
||||||
```
|
|
||||||
|
|
||||||
### Layout
|
|
||||||
|
|
||||||
```
|
|
||||||
src/main/ Electron main process
|
|
||||||
voipms.ts REST client (getDIDsInfo, getSMS, sendSMS)
|
|
||||||
sync.ts history backfill + polling
|
|
||||||
db.ts SQLite schema, FTS5 search, snapshots
|
|
||||||
contacts.ts EDS cache reader + vCard parser
|
|
||||||
secrets.ts keyring-encrypted credentials
|
|
||||||
settings.ts data folder + preferences
|
|
||||||
src/preload/ typed IPC bridge (window.api)
|
|
||||||
src/renderer/ React UI
|
|
||||||
src/shared/ types + phone-number helpers shared by both sides
|
|
||||||
resources/ icon, eds-sources.py (lists live EDS address books)
|
|
||||||
```
|
|
||||||
|
|
||||||
The message table already reserves `kind` and `media_json` columns for MMS support.
|
|
||||||
|
|||||||
Binary file not shown.
|
After Width: | Height: | Size: 145 KiB |
Reference in New Issue
Block a user