All source code single file

2026-09-02 23:47:49 -05:00
parent 0d56e6ebb9
commit 4d504d3440
2 changed files with 319 additions and 0 deletions
@@ -0,0 +1,128 @@
+# Alby Command-line Boosting App
+
+# boostagram
+
+A command-line tool for sending [Podcasting 2.0](https://podcastindex.org/) boostagrams via [AlbyHub](https://github.com/getAlby/hub). The following workflow has been confirmed on NixOS, but should work about the same on other distros. 
+
+## Prerequisites
+
+- NixOS with AlbyHub installed and funded (channels open)
+- Network access to the AlbyHub machine
+- Python 3 and Node.js available on the sending machine
+
+## Setup
+
+### 1. Add packages to configuration.nix
+
+```nix
+environment.systemPackages = with pkgs; [
+  nodejs
+  (python3.withPackages (ps: with ps; [ feedparser ]))
+];
+```
+
+Rebuild:
+
+```bash
+sudo nixos-rebuild switch
+```
+
+### 2. Connect the Alby CLI to AlbyHub
+
+You have two options:
+
+#### Option A: Auth flow (recommended if you have HTTPS)
+
+```bash
+npx @getalby/cli auth https://YOUR_ALBYHUB_ADDRESS --app-name "boostagram"
+```
+
+Open the URL it prints in your browser, approve the connection in AlbyHub, then:
+
+```bash
+npx @getalby/cli auth --complete
+```
+
+#### Option B: NWC connection string (works without HTTPS)
+
+1. Open the AlbyHub web UI in your browser
+2. Go to **Apps** or **NWC Connections**
+3. Create a new connection named "boostagram"
+4. Copy the `nostr+walletconnect://...` string
+5. Paste it into the CLI:
+
+```bash
+npx @getalby/cli connect "nostr+walletconnect://YOUR_CONNECTION_STRING"
+```
+
+### 3. Place the script
+
+Copy `boostagram` somewhere in your `$PATH` (e.g. `~/bin/` or `/usr/local/bin/`):
+
+```bash
+cp boostagram ~/bin/boostagram
+chmod +x ~/bin/boostagram
+```
+
+## Usage
+
+```bash
+boostagram --feed <RSS_FEED_URL> --amount <SATS> --message "<TEXT>" --sender "<NAME>"
+```
+
+### Required flags
+
+| Flag | Description |
+|------|-------------|
+| `--feed` | Podcast RSS feed URL |
+| `--amount` | Total sats to boost (split across recipients automatically) |
+| `--sender` | Your display name |
+
+### Optional flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--message` | Boostagram message text | (none) |
+| `--episode` | Episode title to boost (partial match, case-insensitive) | Latest episode |
+| `--ts` | Playback position in seconds | (none) |
+| `--app-name` | App name in the boostagram metadata | `boostagram` |
+
+### Examples
+
+Boost the last available episode: 
+
+```bash
+python ./boostagram --feed https://linuxunplugged.com/rss --amount 608221 --message "Dis me massage." --sender "poopie mcfartweiner"
+```
+
+Boost a specific episode:
+
+```bash
+boostagram --feed https://linuxunplugged.com/rss \
+           --amount 500 \
+           --message "Loved this episode!" \
+           --sender "YourName" \
+           --episode "Oops! All Shells"
+```
+
+### How it works
+
+1. Fetches the RSS feed and finds the `<podcast:value>` block
+2. If `--episode` is given, matches against episode titles; otherwise uses the latest episode
+3. Splits the sats across all recipients defined in the feed's value block
+4. Constructs a BLIP-0010 boostagram JSON payload
+5. Sends a keysend payment to each recipient via the Alby CLI with the boostagram attached as TLV record 7629169
+
+## Troubleshooting
+
+**"error: no \<podcast:value\> block found in feed"**
+The podcast doesn't support Podcasting 2.0 value blocks. Not all podcasts have this.
+
+**"Timed out waiting for wallet approval"**
+The Alby CLI isn't authenticated. Run the auth flow from step 2 above.
+
+**Auth URL won't load in browser**
+Use the Tailscale IP instead of the hostname, or use Option B (NWC connection string).
+
+**Payments fail individually**
+Check your AlbyHub has sufficient channel balance. Each recipient split is sent as a separate keysend payment.