surplus/docs/onwheels/bridges.md

surplus on wheel bridges

official bridges

there are two currently “official” bridges:

• surplus on wheels: WhatsApp Bridge
• surplus on wheels: Telegram Bridge

bring your own bridge

an informal specification

s+ow bridges are relatively simple as they are:

1. an executable or script

2. that reads in SPOW_TARGETS given by surplus to the bridge, using the standard input (stdin) stream

   1. bridges do not need to account for the possibility of multiple lines sent to stdin

   2. bridges should account for the possibility of comma and space (", " instead of just ",") delimited targets, and strip each target of preceding and trailing whitespace

   3. bridges should recognise a platform based on a prefix
      (e.g. wa: for WhatsApp, tg: for Telegram, etc.)

3. reads SPOW_MESSAGE (~/.cache/spow/message) for the message content

notes:

1. stderr and stdout are redirected to s+ow’s error and output logs respectively unless the -p / --private flag is passed to surplus

2. any errors encountered by the bridge should always result in a non-zero return. error logs will show the exact error code, so feel free to use other numbers than 1

3. persistent data such as credentials and session data storage are to be handled by the bridge itself. consider storing them in $HOME/.local/share/<bridge-name>/, or wherever appropriate

example

if i were to recommend an example on a basic bridge implementation, it would be the Telegram Bridge:

--8<-- "src/spow-telegram-bridge/bridge.py"

!!! note the feature of deleting the last sent message (--delete-last) is a non-standard feature for bridges, and was simply a use case i personally needed. if you're going to implement a bridge, all you really need is the ability to login, logout, and send a message

you can add other features as per the needs of your platform, like how the WhatsApp Bridge has
a `pair-phone` subcommand, or per your use case needs, like in the Telegram Bridge's `--delete-last`.