stream_deck_notion_timer/README.md

Notion Timer — Stream Deck Plugin

A Stream Deck plugin that toggles time tracking in Notion. Press a button to start a timer against a project, press again to stop. Only one timer can run at a time.

---

Staff Installation

Requires Stream Deck installed and up to date.

Open Terminal and run:

curl -s https://gitea.pdmarf.co.uk/pdm/stream_deck_notion_timer/raw/branch/master/install.sh | bash

Stream Deck will open and install the plugin automatically.

First-time setup:

1. Drag a Toggle Timer button onto a key in Stream Deck
2. Click the button — a settings panel appears at the bottom
3. Expand Notion Credentials and fill in your API token, then select your name from the dropdown
4. Select your project from the Project dropdown

---

Auto-Updates

Updates are automatic — no action needed from staff.

The flow:

1. Plugin starts and connects to Stream Deck
2. After 10 seconds it checks version.json on Gitea
3. If a newer version is available, it downloads plugin.js and plugin.js.sig
4. The Ed25519 signature is verified against the public key embedded in the plugin
5. If the signature is valid, the plugin overwrites itself and restarts
6. Stream Deck relaunches the plugin on the new version

If the update server is unreachable or the signature fails, the plugin continues running on the current version unchanged.

---

Developer Workflow

Build & deploy locally

npm run build       # compile + sign

Then copy to Stream Deck:

cp com.pdma.notion-timer.sdPlugin/bin/plugin.js "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/com.pdma.notion-timer.sdPlugin/bin/plugin.js"
cp com.pdma.notion-timer.sdPlugin/bin/plugin.js.sig "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/com.pdma.notion-timer.sdPlugin/bin/plugin.js.sig"
pkill -f "notion-timer"

Release an update to staff

1. Make your changes
2. Bump CURRENT_VERSION in src/plugin.ts and version.json
3. Run:

npm run package
git add .
git commit -m "v1.x.x: description"
git push

Staff machines will pick up the update within 10 seconds of their next Stream Deck start.

Signing key

The Ed25519 private key lives at ~/.notion-timer-signing-key.pem — keep this backed up. If lost, a new key pair must be generated and the plugin redistributed manually to all staff.

---

Architecture

Component	Location	Runtime
Plugin logic	src/plugin.ts	Node.js 20 (under Stream Deck)
Notion API	src/notion.ts	Node.js 20
Settings UI	ui/property-inspector.html	Browser (in Stream Deck app)
PI library	ui/libs/	Browser — from elgatosf/streamdeck-javascript-sdk