Add f7push v0.1: FCM device registry and push API for F7cloud.

Portable occ-based config, OCS endpoints for APK registration, notification relay, and server-side push dispatch.
2026-05-24 10:26:36 +03:00
commit df4e2dddec
17 changed files with 1005 additions and 0 deletions
@@ -0,0 +1,89 @@
+# F7 Push
+
+Mobile push delivery for **F7cloud** accounts via Firebase Cloud Messaging.
+
+Portable: install on any F7cloud server, configure via `occ`, no hardcoded hostnames.
+
+## Install on a server
+
+```bash
+git clone git@git.f7cloud.ru:root/f7push.git /var/www/f7cloud/apps/f7push
+cd /var/www/f7cloud
+sudo -u www-data php occ app:enable f7push
+```
+
+## Configuration (`occ`)
+
+```bash
+# Enable / disable
+sudo -u www-data php occ config:app:set f7push enabled --value=yes
+
+# Firebase (service account JSON from Firebase Console, one line or file)
+sudo -u www-data php occ config:app:set f7push firebase_project_id --value=YOUR_PROJECT_ID
+sudo -u www-data php occ config:app:set f7push firebase_credentials --value='{"type":"service_account",...}'
+
+# Optional: default URL when notification has no link
+sudo -u www-data php occ config:app:set f7push default_click_url --value=https://YOUR-SERVER.f7cloud.ru
+
+# Filter sources (comma-separated app ids, or * for all)
+sudo -u www-data php occ config:app:set f7push enabled_sources --value='spreed,f7support,files'
+
+# Relay F7cloud bell notifications to push
+sudo -u www-data php occ config:app:set f7push listen_notifications --value=yes
+
+# API secret (auto-created on first server push if empty, or set manually):
+sudo -u www-data php occ config:app:set f7push api_secret --value='YOUR_SECRET'
+# Or: bash scripts/generate-secret.sh --regenerate
+```
+
+## API (OCS)
+
+Base: `/ocs/v2.php/apps/f7push/api/v1/`
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/devices` | User session | Register FCM token |
+| DELETE | `/devices/{deviceId}` | User session | Unregister device |
+| GET | `/devices` | User session | List own devices |
+| GET | `/status` | Public | Push enabled / Firebase configured |
+| POST | `/push` | `X-F7-Push-Secret` | Send push to user account |
+| POST | `/push/test` | User session | Test push to own devices |
+
+### Register device (APK)
+
+```json
+POST /ocs/v2.php/apps/f7push/api/v1/devices
+{
+  "deviceId": "stable-android-id",
+  "fcmToken": "...",
+  "platform": "android",
+  "clientApp": "f7cloud-apk"
+}
+```
+
+### Send push (f7support / other apps)
+
+```json
+POST /ocs/v2.php/apps/f7push/api/v1/push
+Header: X-F7-Push-Secret: <secret>
+
+{
+  "userId": "username",
+  "title": "Support",
+  "body": "New reply",
+  "url": "https://server/apps/f7support",
+  "source": "f7support",
+  "priority": "normal"
+}
+```
+
+## Android APK
+
+Repository: `android-webview` on the same server.
+
+1. Add `google-services.json` from Firebase (`applicationId` `ru.forbion.f7cloud`).
+2. Build APK; on login the app registers FCM token via `/devices`.
+
+## Version
+
+0.1.0 — initial release (device registry, FCM send, notification relay, API).