From 2efbcae449f6a4d55594424fd4675c26ba8233dc Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 25 Nov 2025 12:00:48 +0100 Subject: [PATCH] Prepare 0.1.0 changelog and npm-focused quickstart --- CHANGELOG.md | 34 ++++++++++++++++++++++++++++++++++ README.md | 27 +++++++++++++++++---------- 2 files changed, 51 insertions(+), 10 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..aa33b3dc7 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,34 @@ +# Changelog + +## 0.1.0 — 2025-11-25 + +### CLI & Providers +- Bundles a single `warelay` CLI with commands for `send`, `relay`, `status`, `webhook`, `up`, `web:login`/`login`, and tmux helpers `relay:tmux` / `relay:tmux:attach` (see `src/cli/program.ts`). +- Supports two messaging backends: **Twilio** (default) and **personal WhatsApp Web**; `relay --provider auto` selects Web when a cached login exists, otherwise falls back to Twilio polling (`provider-web.ts`, `cli/program.ts`). +- `send` can target either provider, optionally wait for delivery status (Twilio only), output JSON, dry-run payloads, and attach media (`commands/send.ts`). +- `status` merges inbound + outbound Twilio traffic with formatted lines or JSON output (`commands/status.ts`, `twilio/messages.ts`). + +### Webhook, Funnel & Port Management +- `webhook` starts an Express server for inbound Twilio callbacks, logs requests, and optionally auto-replies with static text or config-driven replies (`twilio/webhook.ts`, `commands/webhook.ts`). +- `up` automates end-to-end webhook setup: ensures required binaries, enables Tailscale Funnel, starts the webhook on the chosen port/path, discovers the WhatsApp sender SID, and updates Twilio webhook URLs with multiple fallbacks (`commands/up.ts`, `infra/tailscale.ts`, `twilio/update-webhook.ts`, `twilio/senders.ts`). +- Guardrails detect busy ports with helpful diagnostics and aborts when conflicts are found (`infra/ports.ts`). + +### Auto-Reply Engine +- Configurable via `~/.warelay/warelay.json` (JSON5) with allowlist support, text or command-driven replies, templating (`{{Body}}`, `{{From}}`, `{{MediaPath}}`, etc.), optional body prefixes, and per-sender or global conversation sessions with `/new` resets and idle expiry (`auto-reply/reply.ts`, `config/config.ts`, `config/sessions.ts`, `auto-reply/templating.ts`). +- Command replies run through a process-wide FIFO queue to avoid concurrent executions across webhook, poller, and web listener flows (`process/command-queue.ts`); verbose mode surfaces wait times. +- Claude CLI integration auto-injects identity, output-format flags, session args, and parses JSON output while preserving metadata (`auto-reply/claude.ts`, `auto-reply/reply.ts`). +- Typing indicators fire before replies for Twilio, and Web provider sends “composing/available” presence when possible (`twilio/typing.ts`, `provider-web.ts`). + +### Media Pipeline +- `send --media` works on both providers: Web accepts local paths or URLs; Twilio requires HTTPS and transparently hosts local files (≤5 MB) via the Funnel/webhook media endpoint, auto-spawning a short-lived media server when `--serve-media` is requested (`commands/send.ts`, `media/host.ts`, `media/server.ts`). +- Auto-replies may include `mediaUrl` from config or command output (`MEDIA:` token extraction) and will host local media when needed before sending (`auto-reply/reply.ts`, `media/parse.ts`, `media/host.ts`). +- Inbound media from Twilio or Web is downloaded to `~/.warelay/media` with TTL cleanup and passed to commands via `MediaPath`/`MediaType` for richer prompts (`twilio/webhook.ts`, `provider-web.ts`, `media/store.ts`). + +### Relay & Monitoring +- `relay` polls Twilio on an interval with exponential-backoff resilience, auto-replying to inbound messages, or listens live via WhatsApp Web with automatic read receipts and presence updates (`cli/program.ts`, `twilio/monitor.ts`, `provider-web.ts`). +- `send` + `waitForFinalStatus` polls Twilio until a terminal delivery state (delivered/read) or timeout, with clear failure surfaces (`twilio/send.ts`). + +### Developer & Ops Ergonomics +- `relay:tmux` helper restarts/attaches to a dedicated `warelay-relay` tmux session for long-running relays (`cli/relay_tmux.ts`). +- Environment validation enforces Twilio credentials early and supports either auth token or API key/secret pairs (`env.ts`). +- Shared logging utilities, binary checks, and runtime abstractions keep CLI output consistent (`globals.ts`, `logger.ts`, `infra/binaries.ts`). diff --git a/README.md b/README.md index 6ce27ac8c..056f30787 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,22 @@ Send, receive, auto-reply, and inspect WhatsApp messages over **Twilio** or your personal **WhatsApp Web** session. Ships with a one-command webhook setup (Tailscale Funnel + Twilio callback) and a configurable auto-reply engine (plain text or command/Claude driven). -## Quick Start (5 steps) -1) Prereqs: Node 22+, `pnpm`, a Twilio account with a WhatsApp-enabled number; Tailscale optional for webhooks. -2) Install deps: `pnpm install` -3) Copy `.env.example` → `.env`; set `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` **or** `TWILIO_API_KEY`/`TWILIO_API_SECRET`, and `TWILIO_WHATSAPP_FROM=whatsapp:+15551234567` (plus optional `TWILIO_SENDER_SID`). -4) Send a test: `pnpm warelay send --to +12345550000 --message "Hi from warelay"` -5) Choose how to receive replies: - - Polling (no ingress): `pnpm warelay relay --provider twilio --interval 5 --lookback 10` - - Webhook (automatic): `pnpm warelay up --port 42873 --path /webhook/whatsapp --verbose` - - Personal WhatsApp (no Twilio): `pnpm warelay web:login` then `pnpm warelay send --provider web ...` +## Quick Start (pick your engine) +Install from npm (global): `npm install -g warelay` (Node 22+). Then choose **one** path: + +**A) Personal WhatsApp Web (preferred: no Twilio creds, fastest setup)** +1. Link your account: `warelay web:login` (scan the QR). +2. Send a message: `warelay send --provider web --to +12345550000 --message "Hi from warelay"`. +3. Stay online & auto-reply: `warelay relay --provider web --verbose`. + +**B) Twilio WhatsApp number (for delivery status + webhooks)** +1. Copy `.env.example` → `.env`; set `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` **or** `TWILIO_API_KEY`/`TWILIO_API_SECRET`, and `TWILIO_WHATSAPP_FROM=whatsapp:+15551234567` (optional `TWILIO_SENDER_SID`). +2. Send a message: `warelay send --to +12345550000 --message "Hi from warelay"`. +3. Receive replies: + - Polling (no ingress): `warelay relay --provider twilio --interval 5 --lookback 10` + - Webhook + public URL via Tailscale Funnel: `warelay up --port 42873 --path /webhook/whatsapp --verbose` + +> Already developing locally? You can still run `pnpm install` and `pnpm warelay ...` from the repo, but end users only need the npm package. ## Main Features - **Two providers:** Twilio (default) for reliable delivery + status; Web provider for quick personal sends/receives via QR login. @@ -23,7 +30,7 @@ Send, receive, auto-reply, and inspect WhatsApp messages over **Twilio** or your | Command | What it does | Core flags | | --- | --- | --- | | `warelay send` | Send a WhatsApp message (Twilio or Web) | `--to ` `--message ` `--wait ` `--poll ` `--provider twilio|web` `--json` `--dry-run` | -| `warelay relay` | Auto-reply loop (poll Twilio or listen on Web) | `--provider auto|twilio|web` `--interval ` `--lookback ` `--verbose` | +| `warelay relay` | Auto-reply loop (poll Twilio or listen on Web) | `--provider ` `--interval ` `--lookback ` `--verbose` | | `warelay status` | Show recent sent/received messages | `--limit ` `--lookback ` `--json` | | `warelay webhook` | Run local inbound webhook server | `--port ` `--path ` `--reply ` `--verbose` `--yes` `--dry-run` | | `warelay up` | Turn on webhook + Tailscale Funnel + Twilio callback | `--port ` `--path ` `--verbose` `--yes` `--dry-run` |